These guidelines instruct how to submit issues and contribute code or documentation to the RIDE. There are also many other projects in the larger Robot Framework ecosystem that you can contribute to. If you notice a library or tool missing, there is hardly any better way to contribute than creating your own project. Other great ways to contribute include answering questions and participating discussion on RIDE-users mailing list and other forums, as well as spreading the word about the framework one way or the other.
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. If you are unsure if something is a bug or is a feature worth implementing, you can first ask on RIDE (RIDE at Forum), or on Slack. These and other similar forums, not the issue tracker, are also places where to ask general questions.
Before submitting a new issue, it is always a good idea to check is the same bug or enhancement already reported. If it is, please add your comments to the existing issue instead of creating a new one.
Explain the bug you have encountered so that others can understand it and preferably also reproduce it. Key things to have in good bug report:
-
Version information
-
RIDE version
-
Python interpreter version
-
Operating system and its version
-
-
Steps to reproduce the problem. With more complex problems it is often a good idea to create a short, self contained, correct example (SSCCE).
-
Possible error message and traceback.
Notice that all information in the issue tracker is public. Do not include any confidential information there.
Describe the new feature and use cases for it in as much detail as possible. Especially with larger enhancements, be prepared to contribute the code in the form of a pull request as explained below or to pay someone for the work. Consider also would it be better to implement this functionality as a separate tool outside the core framework.
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.
Often you already have a bug or an enhancement you want to work on in your mind, but you can also look at the issue tracker to find bugs and enhancements submitted by others. The issues vary significantly in complexity and difficulty, so you can try to find something that matches your skill level and knowledge. There are two specific labels to look for when looking for something to contribute: good first issue or help wanted
good first issue-
These issues typically do not require any knowledge of Robot Framework internals and are generally easy to implement or fix. Thus these issues are especially good for new contributors.
help wanted-
These issues require external help to get implemented or fixed.
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 Robot Framework 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.
The basic code setup of RIDE, needs a additional steps since v2.1.1 (November 2024):
-
Forking the project (Web interface)
-
Clone (for example)
git clone [email protected]:robotframework/RIDE.git -
cd RIDE -
pip install -U -r requirements-dev.txt -
git submodule init -
git submodule update
Then you may change to the develop branch, which should be the base for features or fixes branches, and the target for pull requests. Example:
-
git checkout develop -
git submodule init -
git submodule update -
git pull origin develop -
git checkout -b a_new_branch_based_on_develop -
After changes, you add new files,
git add a_new_file -
You add and commit the modified files,
git -a -m "The short message with info about the change -
You push the commit to your fork,
git push origin a_new_branch_based_on_develop -
You may repeat the commit/push and when ready create a Pull Request to your
developbranch, or -
You checkout your
developbranch, and merge withgit merge a_new_branch_based_on_develop -
Later you should keep the
developbranch updated by pulling from your remote,git pull origin develop, or -
By pushing
git push origin develop -
Finaly, you can create a Pull Request from your fork to the target
developbranch of the original RIDE project.
|
Note
|
RIDE graphical user interface, can only exist due the use of wxPython (from wxWidgets). Users wanting to write Python code for RIDE, should be acquainted with wxPython in particular by exploring its demo. |
RIDE uses the general Python code conventions defined in PEP-8. In addition to that, we try to write idiomatic Python and follow the SOLID principles with all new code. 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 (actually, greater than 3.7, currently 3.13). RIDE’s code may still have some Python 2 conditioning, due to its dual compatibility on version 1.7.4.2, and also in the included Robot Framework library from version 3.1.2.
Maximum line length with Python code, including docstrings and comments, is 100 characters. This is also what Black uses by default and their documentation explains why. Notice that we do not have immediate plans to actually take Black into use but we may consider that later.
We are pretty picky about using whitespace. We follow PEP-8 in how to use blank lines and whitespace in general, but we also have some stricter rules:
-
No blank lines inside functions.
-
No blank lines between a class declaration and class attributes or between attributes.
-
Indentation using spaces, not tabs.
-
No trailing spaces.
-
No extra empty lines at the end of the file.
-
Files must end with a newline.
Most of these rules are such that any decent text editor or IDE can be configured to automatically format files according to them.
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. See API documentation section below for more details about documentation syntax, generating API docs, etc.
With new features adequate documentation is as important as the actual functionality. Different documentation is needed depending on the issue.
RIDE’s Wiki is the preferred location for the documentation. This is to promote collaboration from users, and hopefully, to have the content easily updated.
When submitting a pull request with a new feature or a fix, you should include unit 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. Currently RIDE only have unit tests, but proposal for acceptance tests, will be most welcome.
Make sure to run all of the tests before submitting a pull request to be sure that your changes do not break anything. If you can, test in multiple environments and interpreters (Windows, Linux, OS X, different Python versions etc). Pull requests are also automatically tested on continuous integration.
If you want to manually verify the changes, the command invoke devel
is the preferred method. An additional debugging option, allows to start
wxPython inspection tool and a Python console, invoke devel -a --debugconsole.
If you want to install the current code locally, you can do it like
python setup.py install, or by installing in development mode with
pip install -e . and then start with python -m robotide.__init__. For
instructions how to create a distribution that allows installing
elsewhere see BUILD.rst.
Unit tests are great for testing internal logic and should be added when
appropriate.
Unit tests are in utest directory. They can be executed from the main folder with:
invoke test
There is also a shell script (requiring customization for your environment). It allows to run the test files stopping when errors are found. Example:
./test_all.sh utest/namespace # to test with python3 and namespace dir
We don’t have yet acceptance tests, but we really see the need of them. The goal is to have them run on any operating system, and using SikuliLibrary. Please contact us via Slack, if you would like to join this testing group.
Once you have code, documentation and tests ready, it is time to finalize the pull request.
If you have done any non-trivial change and would like to be credited,
remind us to add acknowledge tag to the issue. This way we will add
your name to the release notes, when next release is made.