From 93c28102ad5697e3875c933f518d0bc0760000b1 Mon Sep 17 00:00:00 2001 From: Paul Menzel Date: Wed, 23 Nov 2016 11:24:49 +0100 Subject: [PATCH] Documentation: Use Markdown as markup GitHub support Markdown, and it is pretty popular, so use it here too. --- ...SubmittingPatches => SubmittingPatches.md} | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) rename Documenation/{SubmittingPatches => SubmittingPatches.md} (89%) diff --git a/Documenation/SubmittingPatches b/Documenation/SubmittingPatches.md similarity index 89% rename from Documenation/SubmittingPatches rename to Documenation/SubmittingPatches.md index 4231d4bc9..20570f2b2 100644 --- a/Documenation/SubmittingPatches +++ b/Documenation/SubmittingPatches.md @@ -1,7 +1,8 @@ Here are some guidelines for people who want to contribute their code to this software. -(1) Make separate commits for logically separate changes. +Make separate commits for logically separate changes. +===================================================== Unless your patch is really trivial, you should not be sending out a patch that was generated between your working tree and @@ -57,7 +58,8 @@ in templates/hooks--pre-commit. To help ensure this does not happen, run git diff --check on your changes before you commit. -(2) Describe your changes well. +Describe your changes well. +=========================== The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and @@ -65,8 +67,8 @@ should skip the full stop. It is also conventional in most cases to prefix the first line with "project: " where the project is a filename or identifier for the project, the Bee file is for, e.g. - . vlc: Enable awesome feature - . linux-4.9-rc5: Add a patch +* vlc: Enable awesome feature +* linux-4.9-rc5: Add a patch The description is a summary, and should be a statement, that means, it has to contain a verb. Best, start the statement with a verb in @@ -77,13 +79,13 @@ files you are modifying to see the current conventions. The body should provide a meaningful commit message, which: - . explains the problem the change tries to solve, iow, what is wrong +* explains the problem the change tries to solve, iow, what is wrong with the current code without the change. - . justifies the way the change solves the problem, iow, why the +* justifies the way the change solves the problem, iow, why the result with the change is better. - . alternate solutions considered but discarded, if any. +* alternate solutions considered but discarded, if any. Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy @@ -103,7 +105,8 @@ The "Copy commit summary" command of gitk can be used to obtain this format. -(3) Publish your work in a separate branch. +Publish your work in a separate branch. +======================================= Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch @@ -112,7 +115,8 @@ your patch after generating it, to ensure accuracy. Before sending out, please make sure it cleanly applies to the "master" branch head. -(4) Creating a merge/pull request +Creating a merge/pull request +============================= You often want to add additional explanation about the patch, other than the commit message itself.