topydo/CONTRIBUTING.md

If you're reading this, you may have interest in enhancing topydo. Thank you!

Please read the following guidelines to get your enhancement / bug fixes smoothly into topydo.

General

• Use descriptive commit messages. The post How to write a commit message by Chris Beams has some good guidelines.

Coding style

• Please try to adhere to the coding style dictated by pylint as much possible. I won't be very picky about long lines, but please try to avoid them.
• I strongly prefer simple and short functions, doing only one thing. I'll ask you to refactor functions with massive indentation or don't fit otherwise on a screen.

Testing

• First make sure to have the prerequisites installed to perform the tests:

    pip install .[test]
  

• Then, run the tests with:

    green -r
  

  Obviously, I won't accept anything that makes the tests fail. When you submit a Pull Request, Travis CI will automatically run all tests for various Python versions, but it's better if you run the tests locally first.

• Travis CI will also run pylint and fail when new errors are introduced. You may want to add a pre-push script to your topydo clone before pushing to Github (.git/hooks/pre-push):

   #!/bin/sh
   remote="$1"
  
   if [ $remote = "origin" ]; then
       if ! green; then
           exit 1
       fi
  
      if ! python3 -m pylint --errors-only topydo test; then
          exit 1
      fi
  fi
  
  exit 0
  

  Make sure to run chmod +x .git/hooks/pre-push to activate the hook.

• Add tests for your change(s):

  • Bugfixes: add a test case that covers your bugfix, so the bug won't happen ever again.
  • Features: add test cases that checks various inputs and outputs of your feature. Be creative in trying to break the feature you've just implemented.

• Check the test coverage of your contributed code, in particular if you touched code in the topydo.lib or topydo.command packages:

  coverage report -m
  

  Or alternatively, for a more friendly output, run:

  coverage html
  

  which will generate annotated files in the htmlcov folder. The new code should be marked green (i.e. covered).

  When you create a Pull Request, code coverage will be automatically checked and reported by Codecov.io.