diff options
| -rw-r--r-- | CODECONVENTIONS.md | 28 |
1 files changed, 28 insertions, 0 deletions
diff --git a/CODECONVENTIONS.md b/CODECONVENTIONS.md index 951adee91f..fa90940cc4 100644 --- a/CODECONVENTIONS.md +++ b/CODECONVENTIONS.md @@ -1,3 +1,31 @@ +Git commit conventions +====================== + +Each commit message should start with a directory or full file path +prefix, so it was clear which part of codebase a commit affects. If +a change affects one file, it's better to use path to a file. If it +affects few files in a subdirectory, using subdirectory as a prefix +is ok. For longish paths, it's acceptable to drop intermediate +components, which still should provide good context of a change. +It's also ok to drop file extensions. + +Besides prefix, first line of a commit message should describe a +change clearly and to the point, and be a grammatical sentence with +final full stop. First line should fit within 78 characters. Examples +of good first line of commit messages: + + py/objstr: Add splitlines() method. + py: Rename FOO to BAR. + docs/machine: Fix typo in reset() description. + ports: Switch to use lib/foo instead of duplicated code. + +After the first line, add an empty line and in following lines describe +a change in a detail, if needed. Any change beyond 5 lines would likely +require such detailed description. + +To get good practical examples of good commits and their messages, browse +thry the `git log` of the project. + Python code conventions ======================= |