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 !
If you feel like helping out, but do not have too much time, this would be a great place to start.

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 without any install, 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 https://github.com/ederag/hamster.git hamster-waf-update
# go to the newly created directory, holding the PR version
cd hamster-waf-update
./waf configure build

Then in three separate terminals (to see well separated log messages, otherwise just append an & to each line)

GSETTINGS_SCHEMA_DIR=build/data python3 src/hamster-service.py --log=INFO
GSETTINGS_SCHEMA_DIR=build/data python3 src/hamster-windows-service.py --log=INFO
GSETTINGS_SCHEMA_DIR=build/data python3 src/hamster-cli.py

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

Hacks can be valuable to show the origin of an issue, or pave the way to a solution,
but the goal is also to clarify the code, and improve maintainability in the long run.

• 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!

For people who want to improve their skills in legacy programming, The Legacy Code Programmer's Toolbox by Jonathan Boccara is easy to read and full of good advices. The "key takeaways" found in the first chapter are so spot-on !

• Suspect that writing the code you’re reading must have been harder than it looks.
• Realize that code difficult to read is not the work of one evil character.
• Avoid complaining if you don’t intend to improve the code.
• Take ownership of the part of the codebase you’re working on.

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

• Documentation is important, technical just as much as user facing help.

User-facing help texts.

• The main help system is in the help/C/ folder.
  After a new modification, the result can be quickly seen with yelp help/C/index.page for instance.
  yelp stays alive a while longer after quiting; just Ctrl-C to return to the prompt instantly.

Note: if someone has the skill and dedication, it would be wonderful to upload an html version.
Please follow-up in a new issue, linking to #416.

Technical documentation

There is no documentation system yet, no expressed API either,
as focus is on cleaning up code and improving the user experience.

But docstrings and comments improvements are an integral part of the cleaning.
If in doubt, use this style guide.

Please keep in mind that docstrings also are carefully reviewed, which takes time and effort, even for almost perfect writing (we all have different ways to express things).
So despite the importance, it would be great to address in priority the docstrings or comments that you missed the most while trying to understand the code.

Note: if not fully sure of a writing, please add a review comment on your own PR, so we can either confirm or better explain that part, rather than spend time trying to figure out what you were meaning.
Also sometimes it could be equally useful to file an issue and ask for clarification.
Please try to be precise and give enough context. Just "I don't understand AddFact in client.py" would not help much 🙂.