All contributions are welcome and even though there are no strict or formal requirements to contribute there are some basic rules contributors need to follow:
- Make sure your contribution is original and it doesn’t violate anybody’s copyright
- Make sure tests pass
- Make sure your contribution is tested
Below you can find more information depending on what you are trying to contribute, in case of doubt don’t hesitate to open a PR with your contribution and ask for help.
To run tests you need
GNU Make. If you meet the requirements all you need to do is execute
make tests. All the tests will run inside docker containers you don’t need to worry about the environment.
If you want to contribute documentation you need to be sligthly familiar with sphinx as that’s the framework used in this project (and most python projects) to build the documentation.
In addition, if you want to contribute with tutorials or code examples you need to be familiar with jupyter. The advantage of using jupyter notebooks over just plain text is that notebooks can be tested. This means code examples and tutorials will be tested by the CI and ensure they stay relevant and work.
The easiest way of working with jupyter is by executing
make jupyter in your local machine and pointing your browser to http://localhost:8888/notebooks/docs. If you are adding a new notebook don’t forget to add it to sphinx’s documentation.
Adding new features¶
New features need to come with tests and a tutorial in the form of a jupyter notebook so it can be tested.
Contributing to drivers¶
If you are adding or doing changes to drivers you need to ensure:
- Existing tests pass without modifying them (unless warranted)
- You add relevant tests to ensure future contributors don’t break your contribution unknowingly
In this type of contribution you don’t need to change the tests, you only need to add one or more test case that covers your changes. To do so you will need to provide a directory per test case with a few files. For instance:
- To test parsers
dev_conf- Native configuration
result.json- Expected result after parsing the configuration
- To test translators
data.json- Configuration in structured format you want to translate
res_merge- Native representation in “merge” mode
res_replace- Native representation in “replace” mode
- To test merge operations
data_candidate.json- Candidate configuration in structured format
data_running.json- Running configuration in structured format
res_merge- The expected commands the device will need to execute to go from the running configuration to the candidate one in “merge” mode.
res_replace- The expected commands the device will need to execute to go from the running configuration to the candidate one in “replace” mode.