Skip to content

Commit

Permalink
Documentation: Use Markdown as markup
Browse files Browse the repository at this point in the history
GitHub support Markdown, and it is pretty popular, so use it here too.
  • Loading branch information
pmenzel committed Nov 23, 2016
1 parent 3dea0c8 commit 93c2810
Showing 1 changed file with 13 additions and 9 deletions.
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -57,16 +58,17 @@ 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
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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

0 comments on commit 93c2810

Please sign in to comment.