From e7837355d1f0758a86e097b9728374e7cbfcf5bf Mon Sep 17 00:00:00 2001 From: mathieui Date: Sun, 29 Jul 2012 19:28:38 +0200 Subject: Documentation: contributing help & guidelines --- doc/en/dev/contributing.txt | 71 +++++++++++++++++++++++++++++++++++++++++++++ doc/en/dev/index.txt | 1 + doc/en/index.txt | 1 + 3 files changed, 73 insertions(+) create mode 100644 doc/en/dev/contributing.txt (limited to 'doc') diff --git a/doc/en/dev/contributing.txt b/doc/en/dev/contributing.txt new file mode 100644 index 00000000..6dbda93e --- /dev/null +++ b/doc/en/dev/contributing.txt @@ -0,0 +1,71 @@ +Contributing +============ + +Conventions +----------- + +We don’t have a strict set of conventions, but you should respect PEP8 mostly +(e.g. 4 spaces, class names in CamelCase and methods lowercased with +underscores) except if it means less-readable code (80 chars is often a hassle, +and if you look inside poezio you’ll see lots of long lines, mostly because of +strings). + + +As explained in the link:./overview.html[overview], “global” code goes in +_core.py_, tab-related code goes in _tabs.py_, and ui-related code goes in +_windows.py_. There are other modules (e.g. xhtml.py) but they do not matter +for the application as a whole. + +Commit guidelines +----------------- + +Commits _should_ have a meaninful title (first line), and _may_ have a detailed +description below. There are of course exceptions (for example, a single-line +commit that takes care of a typo right behind a big commit does not need to +say “fix a typo ("azre" → "are") in toto.py line 45454", since the metainfos +already take care of that.), but if you do not have commit access on the +poezio trunk, you can still reset and commit again. + + +Try to do atomic commits: since git is a DVCS, it doesn’t hurt to git add -p +and split the commit into several meaningful small commits ; on the contrary, +it helps to track the changes on different levels. + + +If you have a conflict, solve it with rebase and not merge if the fast-forwards +do not resolve it automatically in your case. This helps to avoid creating +useless merges (and polluting the commit history) when none is needed. + +.Basic case +========================== + + git fetch origin + git rebase origin/master + git push origin master + +========================== + +If your commit is related to an issue on +link:https://dev.louiz.org/project/poezio/bugs[our tracker] (or fixes such an + issue), you can use “Fixes #BUGID” or “References #BUGID” to help with the + tracking. + + +Getting your code into poezio +----------------------------- + +If you have code you want to contribute, you can: + +* Give us a patch and a description of what it does +* Give us a link to a _git_ repo from which we can pull + +The code is of course reviewed and tested a bit, but we trust the contributors +to submit good code. If we can’t integrate the given code into poezio (if it +crashes or has some issues), if the size is small, we may tweak it ourselves +and integrate it, and if not, you are of course free to take our advice into +account and submit it again. + + +If you have already submitted some code and plan to do more, you can ask us + direct commit access on the main repo. + diff --git a/doc/en/dev/index.txt b/doc/en/dev/index.txt index 263151fb..17ca42d6 100644 --- a/doc/en/dev/index.txt +++ b/doc/en/dev/index.txt @@ -5,3 +5,4 @@ This section of the documentation is here to provide a quickstart for someone willing to start hacking poezio. * link:overview.html[Overview] +* link:contributing.html[Contributing] diff --git a/doc/en/index.txt b/doc/en/index.txt index b0ba0af1..e7d89277 100644 --- a/doc/en/index.txt +++ b/doc/en/index.txt @@ -15,4 +15,5 @@ Available pages * link:keys.html[Keys] * link:plugins/index.html[Available Plugins] * link:plugins.html[Developing plugins] +* link:dev/index.html[Developing Poezio] * link:xep.html[Current XEP support] -- cgit v1.2.3