These guidelines instruct how to submit issues and contribute code or documentation to the Robocop project. Another way to contribute includes participating in discussion and answering questions on our Slack channel #robocop-linter located in Robot Framework workspace. We have some dedicated channels for all different types of topics. One of the best ways to support is to help us grow so don't hesitate and spread the word about Robocop!
These guidelines expect readers to have a basic knowledge about open source as well as why and how to contribute to open source projects. If you are totally new to these topics, it may be a good idea to look at the generic Open Source Guides first.
Bugs and enhancements are tracked in the issue tracker.
Before submitting a new issue, it is always a good idea to check if the same bug or enhancement is already reported. If it is, please add your comments to the existing issue instead of creating a new one.
They'll fix you. They fix everything. - Robocop
The preferred way to report a bug is to create an issue using Bug report template and fill in the blanks:
- Explanation of a bug
- Steps to reproduce the problem
- Output with error message
- Expected behavior
- Version information (Robocop version, Python version, operating system etc.)
Notice that all information in the issue tracker is public. Do not include any confidential information there.
To suggest an idea for the project please create an issue using Feature request template. Try to write clear and concise description of why this should be useful and what needs to be done to accomplish the goal.
If you have fixed a bug or implemented an enhancement, you can contribute your changes via GitHub's pull requests. This is not restricted to code, on the contrary, fixes and enhancements to documentation and tests alone are also very valuable.
On GitHub pull requests are the main mechanism to contribute code. They are easy to use both for the contributor and for the person accepting the contribution, and with more complex contributions it is easy also for others to join the discussion. Preconditions for creating pull requests are having a GitHub account, installing Git and forking the Robocop project.
GitHub has good articles explaining how to set up Git, fork a repository and use pull requests and we do not go through them in more detail. We do, however, recommend to create dedicated topic branches for pull requests instead of creating them based on the master branch. This is especially important if you plan to work on multiple pull requests at the same time.
Stay out of trouble. - Robocop
Robocop uses the general Python code conventions defined in PEP-8. An important guideline is that the code should be clear enough that comments are generally not needed.
All code, including test code, must be compatible with all supported Python interpreters and versions. Most importantly this means that the code must support Python 3.6+ and Robot Framework 3.2.1+.
To ensure high quality of the code we use pylama static code analysis tool to check
against common errors and mistakes. The tool needs to be run with
configuration file pylama.ini located in the root of the repository.
Execute the command before creating a pull request (you must have pylama
installed):
pylama -o pylama.ini
Docstrings should be added to public APIs, but they are not generally needed in internal code. When docstrings are added, they should follow PEP-257.
With new features adequate documentation is as important as the actual
functionality. Different documentation is needed depending on the issue
but most of it is located inside docs directory. The files are usually
written using reStructuredText format (.rst).
To generate our documentation use nox tool that will create environment with required dependencies and generate
the documentation. Documentation will be available under docs/_build/index.html path:
nox -s docs
Robocop's main features are explained in the README. The whole documentation is available here.
Every change is required to pass pre-commit checks. To install pre-commit tool run:
pip install pre-commit
Then install the pre-commits for this repository run in the root:
pre-commit install
Now all commits will trigger pre-commit script that will scan & format your code.
When submitting a pull request with a new feature or a fix, you should always include tests for your changes. These tests prove that your changes work, help prevent bugs in the future, and help document what your changes do. Depending on the change, you may need acceptance tests, unit tests or both.
Make sure to run all of the tests before submitting a pull request to be sure that your changes do not break anything. Pull requests are also automatically tested on continuous integration.
Most of our tests use pytest. To use it install Robocop with dev profile:
pip install robotframework-robocop[dev]
To run pytest tests navigate to directory with test files and run:
pytest .
Pytest will automatically discover all the tests, run them and display results. Make sure that tests do not fail.
Robocop contains nox file for running the tests on all supported major Robot Framework versions and generating the coverage or docs. The nox tool will create the virtual environment and install required dependencies for you.
Follow installation instruction from the nox documentation page. To execute Robocop tests run:
nox
Run the following command to see all possible sessions (acting as environments or targets):
nox --list
You can select only one session per run. For example, to only run tests for Python==3.10 and Robot Framework==3.*:
nox --session "unit-3.10(robot_version='3')"
Unit tests are great for testing internal logic and should be added when
appropriate. They are located in tests/utest directory.
Acceptance tests are dynamically generated for every rule in Robocop. Test data
should be located in tests\atest\rules\{rules_category} directory. If your rule has name "rule-name"
it will expect rule-name directory with expected_output.txt file inside.
You can put one or more *.robot files inside - it will be autoscanned with --include "rule-name" option.
Robocop output will be compared with content of expected_output.txt file.
When updating expected_output.txt file you can use two macro variables: ${rules_dir} and ${/}.
The first is path to rules directory (so the correct path in Robocop output will be printed) and the
second is path separator - under Windows and / under Linux.
If you wish to use additional configuration or use different that default test data directory follow
instructions from pytest_generate_tests method.
In case you want to run only single test (not all dynamically generated ones) you can run:
pytest --rule rule-name tests\atest
Simple E2E tests are also included in repository in tests/e2e directory.
They are being run automatically along with unit tests when pytest is
executed.
To execute performance tests on every rule run:
pytest --benchmark-enable tests
Add --benchmark-save=benchmark_results option to save your test results in a JSON file. It can be later used to compare results between the different runs. See [here](https://pytest-benchmark.readthedocs.io/en/stable/comparing.html) for more details.
Tests coverage cannot drop under 90%. If your changes affect the coverage significantly, please write new tests to satisfy the expected threshold, otherwise continuous integration will not permit to merge the changes.
To calculate coverage locally run:
coverage run -m pytest
and then:
coverage html
You can also use nox tool:
nox -s coverage
HTML files will be generated - navigate to htmlcov directory and open index.html file.
Thank you for your cooperation. Good night. - Robocop