some additions to contributors guide
+This is some guidance for RSAtoolbox contributors, but our approach evolves over time. Don't hesitate to contact @ilogue (Jasper) or @HeikoSchuett with any questions.
+
+
Your cycle
==========
-1. If you identify something that has to be fixed or done: create an issue. Issues can be associated with projects.
+1. If you identify something that has to be fixed or done: create an issue. Discussions
+or questions about the theory or best practices should be filed as Github Discussions.
2. If you want to start coding or documenting something, the first step is to check if anyone else is working on this in the list of Pull Requests. If not, create a branch on your local machine, commit something small such as a note or empty file, and push the commit to the same branch on GitHub. Then you can then open a Pull Request. This is for two reasons: you're communicating to the team that you're working on this (so we're not doing things twice), and it gives you and the others an easy way to track your progress.
3. Commit regularly (typically every 10-30 minutes) and give your commits useful messages. "Changes to the data package" does not say anything about what you've done, "Added new feature model" does. If your commit is too large this makes it harder to write a short message.
-4. Write unit-tests to cover your new code. This is easier when you recently wrote the code. Also we require test coverage for your changes to be merged into master!
-5. When you're done with the feature, ask for reviews from two team members or ask the maintainers for help.
-6. When the reviewers have approved the Pull Request, they will merge it into the master branch. At this point you want to checkout the master branch again and pull so that you have your latest changes, and can open a new branch for a new feature.
+4. Write unit-tests to cover your new code. This is easier when you recently wrote the code. Tip: try writing tests before you implement the code. The test should assert at least the most important outcomes of the functionality (typically the value returned).
+5. Add Python type annotations where practical.
+6. When you're done with the feature, ask for reviews from two team members or ask the maintainers for help.
+
-Here is an example shell command to build rsatoolbox, install it in your environment, and run the unit tests on it, in one go:
+How-to
+======
-```sh
-python -m build && sleep 1 && pip install --pre --force-reinstall dist/*.whl && pytest
-```
+1. `pip install -r requirements.txt` install rsatoolbox dependencies (and repeat when you make changes)
+2. `pip install -r tests/requirements.txt` install test dependencies (and repeat when you make changes)
+3. `pip uninstall rsatoolbox` uninstall rsatoolbox in your environment
+4. `rm dist/*` remove any previously built packages if necessary
+5. `python -m build` compile a new rsatoolbox package with your latest changes
+6. `pip install dist/*` install the new package
+7. `pip install -r requirements.txt` install the new package
+8. `pip install -r tests/requirements.txt` install the new package
+9. `pytest` run the unit tests on the installed version of rsatoolbox
+10. run linting tools such as `flake8`, `vulture` to discover any style issues
Rules
@@ -20,12 +33,13 @@ Rules
1. Only through Pull Requests can you submit changes or additions to the code.
2. Every Pull Request has to be reviewed by two team members.
-3. New code should be covered 100% by unit tests.
+3. New code should have useful unit tests.
4. Code should pass the `pylint` style check.
5. Functions, classes, methods should have a `Google-style docstring`.
6. Larger new features should come with narrative documentation and an example.
7. When you're ready for your Pull Request to be reviewed, in the top right corner you can suggest two reviewers,
or alternatively, ping @ilogue or @HeikoSchuett and we will assign reviewers.
+8. Consider how to handle NaNs in the user input. If your code can't handle them, you can throw an exception.
Deployment
