How to contribute

Send in bug reports, feature request, comments

• Check if a relevant issue already exists (including closed ones)

• If not, please feel encouraged to let us know :)

  Please state the version you are using. In case of a development version, this is the output of

  git describe --abbrev=40 --always --dirty=+

• Look out for help wanted flags. You might just have the knowledge needed to overcome a difficulty.

Test

Feedback on pending pull requests is precious !

Contributing for the first time can be a bit intimidating. But it is worth it !

Please file an issue or edit this wiki if something is not clear.

One-shot test

At the bottom of the pull request, look for a line similar to

Add more commits by pushing to the waf-update branch on ederag/hamster.

to try out this pull request, the one-shot solution (thanks Gerald !) is
[replace waf-update with the relevant branch name and ederag/hamster with the relevant repo]

# clone the waf-update branch of ederag/hamster, into the hamster-waf-update directory.
git clone --branch=waf-update [email protected]:ederag/hamster.git hamster-waf-update
# go to the newly created directory, holding the PR version
cd hamster-waf-update

Then follow these instructions.

Of course creating a new directory to try out any new modification can become tedious; it is possible to create a local clone of a fork, linked to the upstream (main project, read-only) repository.

Fork

• Fork this project, making sure to follow all the steps, until

  git remote -v displays fetch and push lines both for origin and upstream.

• It is then possible to checkout a specific pull request, e.g. PR #421 (replace with the relevant PR number) with

  git fetch upstream pull/421/head && git checkout pr/421

  This process can be simplified. In the fork clone directory, edit .git/config, adding the line (adapted from the git book)

  fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*
  

  Then to try out PR #421 (replace with the relevant PR number),

  git fetch --all
  git checkout pr/421
  

• After testing, your local pr/421 branch can be deleted:

  git checkout master && git branch -D pr/421

  which can also be most easily done from the graphical interface for the git history:

  # --all to get all branches
  gitk --all

Contribute code

• Before any change, it is good practice to issue

  git fetch --all  # get all information available (including upstream)
  git checkout upstream/master  # start from the upstream master branch

• Create a topic branch: git checkout -b my_branch

• Push to your branch - git push origin my_branch

  or just git push, which will provide the correct command to use.

  Follow the link that appears, or go to your github fork repo to...

• Submit a Pull Request with your branch

• That's it!

Review Code

• If you feel somewhat competent with python but don't want to commit to write code yourself, we could still use a hand having you review our PRs.
• No amount of testing and linting is a substitute for another set of eyes going over our code.
• If you are game, please get in touch and we will either let you know if there is a new PR or you just use githubs watch function.

Translate

[TODO]

Document

• Hamsters documentation is in a rather bad state. We do need technical documentation just as much as user facing help texts.
• If you feel like helping out, but don't want/can't commit too heavily timewise, this would be a great place to start.

User-facing help texts.

• For the time beeing, just use this wiki with to store your contributions. Please make sure to specify where you feel this should be displayed.

Technical documentation

• Currently the backend-code is under heavy refactoring. Although it could generaly greatly profit from doc-strings it most likly would be a waste of anybodys time at this point.
• However, hamster-cli and all frontend related code (hamster-GTK) most certainly could benefit from cleaned up sphinx compatible rst-docstring that may even feature the occasional :param:.
• Don't be disheartened, every docstring helps lets tackle one at a time!