diff --git a/Documenation/SubmittingPatches.md b/Documenation/SubmittingPatches.md new file mode 100644 index 000000000..7accb1d25 --- /dev/null +++ b/Documenation/SubmittingPatches.md @@ -0,0 +1,87 @@ +Here are some guidelines for people who want to make changes +to this repository. + +Commits +======= + +Make separate commits for logically separate changes. + +The first line of each commit message should be a short description (50 +characters is the soft limit, see DISCUSSION in git-commit(1)), and +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 + +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 +imperative mood. + +If in doubt which identifier to use, run "git log --no-merges" on the +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 + with the current code without the change. + +* justifies the way the change solves the problem, iow, why the + result with the change is better. + +* 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 +to do frotz", as if you are giving orders to the codebase to change +its behaviour. Try to make sure your explanation can be understood +without external resources. Instead of giving a URL to a mailing list +archive, summarize the relevant points of the discussion. + +If you want to reference a previous commit in the history of a stable +branch, use the format "abbreviated sha1 (subject, date)", +with the subject enclosed in a pair of double-quotes, like this: + + Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30) + noticed that ... + +The "Copy commit summary" command of gitk can be used to obtain this +format. + +If your description starts to get too long, that's a sign that you +probably need to split up your commit to finer grained pieces. +That being said, patches which plainly describe the things that +help reviewers check the patch, and future maintainers understand +the code, are the most beautiful patches. Descriptions that summarise +the point in the subject well, and describe the motivation for the +change, the approach taken by the change, and if relevant how this +differs substantially from the prior version, are all good things +to have. + +Oh, another thing. We are picky about whitespaces. Make sure your +changes do not trigger errors with the sample pre-commit hook shipped +in templates/hooks--pre-commit. To help ensure this does not happen, +run git diff --check on your changes before you commit. + + +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 +is trying to achieve. Make sure to review +your patch after generating it, to ensure accuracy. Before +sending out, please make sure it cleanly applies to the "master" +branch head. + +Creating a merge/pull request +============================= + +You often want to add additional explanation about the patch, +other than the commit message itself. + +Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do.