These guidelines instruct how to submit issues and contribute code to the SeleniumLibrary project. Other great ways to contribute include answering questions and participating discussion on robotframework-users mailing list and other forums as well as spreading the word about the framework one way or the other.
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 robotframework-users list. This 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:
- Python version information
- SeleniumLibrary, Selenium and Robot Framework version
- Browser type and version.
- Also the driver version, example ChromeDriver 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 in an issue. Especially with larger enhancements, be prepared to contribute the code in 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 library outside the SeleniumLibrary.
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.
You may find a mix of param names for the same thing, for example ``error`` and message to indicate a custom error message. Moving forward we are going to prefer ``message`` over ``error``. We may deprecate ``error`` in the future but for going forward, please use ``message`` with your keywords.
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.
On GitHub pull requests are the main mechanism to contribute code. They are easy to use both for the contributor and for person accepting the contribution, and with more complex contributions it is easy also for others to join the discussion. Preconditions for creating a pull requests are having a GitHub account, installing Git and forking the SeleniumLibrary 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 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.
This project requires that pull request contains linear history of commits and we do not allow that pull request contains merge commits or other noise. This helps the review process and makes the maintenance easier for the project administrators. Generally it is recommended to do git pull --rebase instead of the git pull --merge when there is need pull changes from upstream.
SeleniumLibrary 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.
Docstrings should be added to public keywords but are not generally needed in internal code. When docstrings are added, they should follow PEP-257. See Documentation section below for more details about documentation syntax, generating docs, etc.
The code should be formatted with Black and errors found by flake8 should be fixed. Black and flake8 can be run by using command:
inv lint
By default flake8 ignores line length error E501, but it does not ignore warning W503. In practice Black formats list access like this:
list[1 : 2]
But flake8 will display an warning about it. This should be manually fixed to look like:
list[1:2]
With new features or enhancements adequate documentation is as important as the actual functionality. Different documentation is needed depending on the issue.
The main source of documentation should be placed in to the library and individual keywords.
- Other keywords and sections in the library introduction can be referenced with internal links created with backticks like `Example Keyword`
- When referring to arguments, argument names must use in inline code style created with double backticks like ``argument``.
- Examples are recommended whenever the new keyword or enhanced functionality is not trivial.
- All new enhancements or changes should have a note telling when the
change was introduced. Often adding something like
New in SeleniumLibray 1.8.is enough.
Keyword documentation can be easily created using invoke task:
inv keyword_documentation
Resulting docs should be verified before the code is committed.
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 an 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. If you can, test in multiple browsers and versions (Firefox, Chrome, IE, Edge etc). Pull requests are also automatically tested on Travis CI.
Most of SeleniumLibrary's testing is done using acceptance tests that naturally use Robot Framework itself for testing. Every new functionality or fix should generally get one or more acceptance tests.
Unit tests are great for testing internal logic and should be added when appropriate. For more details see Unit and acceptance tests.
SeleniumLibrary's continuous integration (CI) servers are visible through Travis CI. For more details about how to run test and how Travis CI integration is implemented can be found from the `test/README.rst`_.
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.
Conflicts can occur if there are new changes to the master that touch the same code as your changes. In that case you should sync your fork and resolve conflicts to allow for an easy merge.