Rework CONTRIBUTING instructions

CONTRIBUTING.md

@@ -1,182 +1,209 @@
-Contributing to Timewarrior
+# Contributing to Timewarrior
-===========================
-
-Contributing a patch
---------------------
-
-The public stable branch for the latest release is `master`. We never commit to
-the master branch.
-
-The main branch for development is named something like `1.2.3`. This is the
-branch where your changes must go. If you see two branches, `1.2.3` and
-`1.2.4`, then choose the higher-numbered branch.
-
-Any patch against `master`, or an older development branch, means additional
-merge work for maintainers, and will not be accepted. If your change is on the
-wrong branch, rebase it onto the right branch. Then retest before submitting.
-
-By contributing a patch, you are declaring that you have the right to submit
-the code under the project licensing terms.
-
 
 Do I need to be a developer to contribute?
-------------------------------------------
 
 No, we need help from a variety of skilled or organized individuals.
+Anyone can contribute, and everyone is encouraged to do so.
 
-Here are the different ways you might conѕider contributing. Anyone can
+Here are the different ways you might conѕider contributing:
-contribute, and everyone is encouraged to do so. Here are many ways to
-contribute that may not be immediately obvious to you:
 
-  - Use the project, become familiar with it, and make suggestions. There are
+1. Reviews
-    always ongoing discussions about new features and changes to existing
+1. Bug reports
-    features.
+1. Feature requests
+1. Code contribution
 
-  - Join us in the #taskwarrior IRC channel on freenode.net. Many great ideas,
+Please read the respective section below about the details.
-    suggestions, testing and discussions have taken place there. It is also
-    the quickest way to get help, or confirm a bug.
 
-  - Review documentation: there are man pages, online articles, tutorials and
+Otherwise you can spread the word and recommend Timewarrior to your friends and colleagues.
-    so on, and these contain many errors, or they may not convey ideas in the
-    best way. Perhaps you can help improve it. Contact us - documentation is
-    a separate effort from the codebase, and includes all web sites, and all
-    are available using git.
-
-  - Take a look at the bug database, and help triage the bug list. This is a
-    review process that involves confirming bugs, providing additional data,
-    information or analysis. Bug triage is very useful and much needed. You
-    could check to see that an old bug is still relevant - sometimes they are
-    not. Need permissions to modify issues? Ask.
-
-  - Review the source code, and point out inefficiencies, problems, unreadable
-    functions, bugs and assumptions.
-
-  - Fix a bug. For this you'll need C++ and Git skills, but this is one of
-    the largest ways you can contribute. We welcome all bug fixes, provided
-    the work is done well and doesn't create other problems or introduce new
-    dependencies. We recommend talking to us before starting. Seriously.
-
-  - Add unit tests. Unit tests are likely the most useful contributions of
-    all, because they not only improve the quality of the code, but prevent
-    future regressions, therefore maintaining quality of subsequent releases.
-    Plus, broken tests are a great motivator for us to fix the causal defect.
-    You'll need Python/C++ skills.
-
-  - Add a feature. Well, let's be very clear about this: adding a feature is
-    not usually well-received, and if you add a feature and send a patch, it
-    will most likely be rejected. The reason for this is that there are many
-    efforts under way, in various code branches. There is a very good chance
-    that the feature you add is either already in progress, or being done in a
-    way that is more fitting when considering other work in progress. So if
-    you want to add a feature, please don't. Start by talking to us, and find
-    out what is currently under way or planned. You might find that we've
-    already rejected such a feature for some very good reasons. So please
-    check first, so we don't duplicate effort or waste anyone's time.
-
-  - Spread the word. Help others become more effective at managing tasks.
-
-  - Encouragement. Tell us what works for you, and what doesn't.
-
-  - Request a feature. This not only tells us that you think something is
-    missing from the software, but gives us insights into how you use it.
-    Plus, you might get your feature implemented.
 
 
-How to make a patch
+## Reviews
--------------------
 
-Clone the repository from the right place. Do not clone from our github mirror,
+Use the project, become familiar with it, and make suggestions.
-we don't use it. Do not patch the contents of one of our tarballs.
+There are always ongoing discussions about new features and changes to existing features.
+Tell us what works for you, and what doesn't.
 
-    $ git clone --recursive https://github.com/GothenburgBitFactory/timewarrior timewarrior.git
+Join us in the #taskwarrior IRC channel on freenode.net.
-    $ cd timewarrior.git
+Many great ideas, suggestions, testing and discussions have taken place there.
+It is also the quickest way to get help, or confirm a bug.
 
-Find the latest development branch, and checkout.
+Review documentation: there are man pages, online articles, tutorials and so on, and these may contain errors, or they may not convey ideas in the best way.
+You can help improve it.
+Documentation is a separate effort from the codebase, and includes all web sites, and all are available using git.
 
-    $ git branch -a
+Take a look at the bug database, and help triage the bug list.
-    * master
+Bug triage is very useful and much needed.
-    remotes/origin/1.2.3
+This is a review process that involves confirming bugs, providing additional data, information or analysis.
-    remotes/origin/1.2.4
+Re-test bug reports on different environments and versions.
-    remotes/origin/HEAD -> origin/master
+You could check to see that an old bug is still relevant - sometimes they are not.
-    remotes/origin/master
-    $ git checkout 1.2.4
-    $ git submodule init
-    $ git submodule update
 
-Prepare your fix. Use a commit message that matches the prevailing format.
+Review the source code, and point out inefficiencies, problems, unreadable functions, bugs and assumptions.
-See 'git log' for examples.
-
-    $ git commit -m '<category>: <description>'
-
-Make sure the test suite passes:
-
-    $ cd test
-    $ make
-    $ ./run_all
-
-If your fix doesn't pass all tests, change it, and squash your commits into one
-commit that works. We do continuous integration, and we want all commits, if
-possible, to not fail.
-
-If you add new functionality, add new tests.
-
-Make a patch file:
-
-    $ git format-patch HEAD^
-
-Take the resulting 0001-xxxxxxx.patch file and attach it to an email that is
-addressed to support@gothenburgbitfactory.org. Do not paste the patch inline in the
-message, attach it instead. This allows the maintainer to save the attachment
-intact and unmodified by the mail client.
-
-In your message, be sure to convince us that you ran the test suite. If you
-want to go the extra mile, update the ChangeLog and add your name to the
-AUTHORS file in the right place.
 
 
-What happens next?
+## Bug reports
-------------------
 
-Your patch will be reviewed by the maintainers. You may receive feedback, which
+Before you submit a bug report, make sure you are using the latest version of Timewarrior. 
-may include requested changes. Your patch may be accepted and applied
+Also please take your time and scan the current bug tickets on our [Github issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Abug) whether your issue has already been reported.
-immediately.
 
-Your authorship will be preserved in the commit. We want you to be properly
+When you submit a bug report, be precise and put as much information into your bug report as possible.
-credited for your work.
+You should at least provide
+* your version of Timewarrior (output of `timew --version`)
+* your OS version information
+* your Python version (output of `python --version`)
 
-Near the end of the development cycle, when a release is close, your patch may
+Your bug report should describe what the bug is and provide the necessary minimal steps to reproduce it.
-be held until the next development cycle begins, unless it is shown to be
+
-minimal and not destabilizing. In mid-cycle your patch may be immediately
+An example:
-applied and pushed.
+
+    When I do this
+    And I do that
+    And I call "timew command"
+    Then I should get "FOO"
+    But the actual output is "BAR"
 
 
-What are the causes for a patch to be rejected?
+## Feature requests
------------------------------------------------
 
-Most likely if your patch is rejected, there are some good reasons. This should
+As for bug reports, you should check our [Github issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aenhancement) whether your feature has already been requested.
-be made clear, with recommendations for improving the patch. Please rework the
+
-patch and resubmit.
+When you submit a feature request, provide a use case which captures the overall intention of your feature, not the technical implementation.
+
+As an example
+
+    I want to visualize time differences in reports
+
+is better than
+
+    I want this output to appear in red and bold letters
+
+This not only tells us that you think something is missing from the software, but gives us insights into how you use it.
+Plus, you might get your feature implemented.
+
+
+## Code contribution
+
+There are different ways you can contribute code to the project:
+
+1. Add extensions
+1. Add tests
+1. Fix bugs
+1. Add features
+
+
+### Extensions
+
+Extensions are standalone programs or scripts that consume Timewarrior data output.
+
+Extensions are the easiest way to contribute as you only need to adhere to the extension API, but are otherwise free in your choice of programming language and style. 
+
+Consult the [documentation](https://taskwarrior.org/docs/timewarrior/api.html) on how you can use the extension API.
+
+
+### Tests, Bug-fixes and Features
+
+In general your contributions have to be associated with an issue on our [Github issue tracker](https://github.com/GothenburgBitFactory/timewarrior/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen).
+See the sections above on how to submit bug reports and feature requests.
+
+Code contributions are only accepted as pull-requests.
+See the next section on how to make a pull-request.
+
+Any code contributions should have sufficient test coverage.
+
+When writing bug-fixes, first write a test to confirm it, then add the commit to fix it.
+When implementing a feature, make sure its behaviour is defined by tests.
+
+Tests are likely the most useful contributions of all, because they not only improve the quality of the code, but prevent future regressions, therefore maintaining quality of subsequent releases.
+
+Nevertheless, all code has to adhere to the coding style guidelines and project architecture. See the respective section below.
+
+If you want to go the extra mile, update the ChangeLog and add your name to the AUTHORS file in the right place.
+
+By contributing, you are declaring that you have the right to submit the code under the project licensing terms.
+
+ 
+## How to make a pull-request
+
+The main branch for development is named `dev`.
+This is the branch where your changes must go.
+The `master` branch always points to the latest release.
+No development takes place here.
+
+To make a pull request you need to have a Github account.
+
+1. Fork the [Timewarrior repository](https://github.com/GothenburgBitFactory/timewarrior) on Github.
+1. Checkout the development branch.
+
+       $ git checkout dev
+
+1. Create a feature branch.
+
+       $ git checkout -b feature_branch
+
+1. Commit your changes, and finally push to the remote repository.
+   Use a commit message that matches the prevailing format. (See `git log` for examples.)
+   
+       $ git commit -am '<issue>: <description>'
+       ...
+       $ git push origin feature_branch
+
+1. Create the pull request on Github.
+
+## What happens next?
+
+Your patch will be reviewed by the maintainers.
+You may receive feedback, which may include requested changes.
+Your patch may be accepted and applied immediately.
+
+Your authorship will be preserved in the commit.
+We want you to be properly credited for your work.
+
+Near the end of the development cycle, when a release is close, your patch may be held until the next development cycle begins, unless it is shown to be minimal and not destabilizing.
+In mid-cycle your patch may be immediately applied and pushed.
+
+
+## What are the causes for a patch to be rejected?
+
+Most likely if your patch is rejected, there are some good reasons.
+This should be made clear, with recommendations for improving the patch.
+Please rework the patch and resubmit.
 
 Here are some reasons that cause patch rejection:
 
-- The code wasn't tested, or breaks the test suite. Every commit should improve
+- The code wasn't tested, or breaks the test suite.
-  the project.
+  Every commit should improve the project.
 
-- New functionality was submitted without supporting tests. Without tests, how
+- New functionality was submitted without supporting tests.
-  would we know it works on all platforms?
+  Without tests, how would we know it works on all platforms?
 
-- New functionality, or modified behavior was not first cleared by the
+- New functionality, or modified behavior was not first cleared by the maintainers as being desirable.
-  maintainers as being desirable. We don't want you to waste your time either.
+  We don't want you to waste your time either.
-  But we do have a plan, and all changes must conform to the plan, otherwise
+  But we do have a plan, and all changes must conform to the plan, otherwise it morphs the project into something we don't want.
-  it morphs the project into something we don't want.
 
-- The code does not follow the formatting of the surrounding code. Your code
+- The code does not follow the formatting of the surrounding code.
-  should blend in perfectly, and not stand out for reasons of formatting,
+  Your code should blend in perfectly, and not stand out for reasons of formatting, naming convention, tabs etc.
-  naming convention, tabs etc.
 
 - The changes need supporting documentation changes which were not made.
 
 - Inefficient, non-portable, or broken code.
 
 
-http://taskwarrior.org
+## Coding style
+
+The general guideline is simply this:
+
+> Make all changes and additions such that they blend in perfectly with the surrounding code, so it looks like only one person worked on the source, and that person is rigidly consistent.
+
+To be a little more explicit, the common elements across the languages are:
+
+* Indent code using two spaces, no tabs
+* With Python, follow PEP8 as much as possible
+* Surround operators and expression terms with a space
+* No cuddled braces
+* Stick to 80 columns where possible, although exceptions are fine
+* Class names are capitalized, variable names are not
+
+We target Python 2.7 so that our test suite runs on the broadest set of platforms.
+This will likely change in the future and 2.7 will be dropped.
+
+We can safely target C++11 because all the default compilers on our supported platforms are ready.
+Feel free to use C++14 and C++17 provided that all build platforms support this.

README.md

@@ -51,7 +51,7 @@ At the site you'll find online documentation, downloads, news and more.
 Your contributions are especially welcome.
 Whether it comes in the form of code patches, ideas, discussion, bug reports, encouragement or criticism, your input is needed.
 
-For support options, take a look at:
+For support options, take a look at [CONTRIBUTING.md](CONTRIBUTING.md) or visit
 
     http://taskwarrior.org/support