|
| 1 | +Contribution guidelines |
| 2 | +======================= |
| 3 | + |
| 4 | +These guidelines instruct how to submit issues and contribute code to the |
| 5 | +[Selenium2Library project](https://github.com/robotframework/Selenium2Library). |
| 6 | +Other great ways to contribute include answering questions and participating |
| 7 | +discussion on [robotframework-users] |
| 8 | +(https://groups.google.com/forum/#!forum/robotframework-users) mailing list |
| 9 | +and other forums as well as spreading the word about the framework one way or |
| 10 | +the other. |
| 11 | + |
| 12 | + |
| 13 | +Submitting issues |
| 14 | +----------------- |
| 15 | + |
| 16 | +Bugs and enhancements are tracked in the [Hélio's fork issue tracker] |
| 17 | +(https://github.com/robotframework/Selenium2Library/issues). If you are |
| 18 | +unsure if something is a bug or is a feature worth implementing, you can |
| 19 | +first ask on [robotframework-users] |
| 20 | +(https://groups.google.com/forum/#!forum/robotframework-users) list. This and |
| 21 | +other similar forums, not the issue tracker, are also places where to ask |
| 22 | +general questions. |
| 23 | + |
| 24 | +Before submitting a new issue, it is always a good idea to check is the |
| 25 | +same bug or enhancement already reported. If it is, please add your comments |
| 26 | +to the existing issue instead of creating a new one. |
| 27 | + |
| 28 | +Reporting bugs |
| 29 | +~~~~~~~~~~~~~~ |
| 30 | +
|
| 31 | +Explain the bug you have encountered so that others can understand it |
| 32 | +and preferably also reproduce it. Key things to have in good bug report: |
| 33 | +
|
| 34 | +1. Version information |
| 35 | +
|
| 36 | + - Selenium2Library, Selenium and Robot Framework version |
| 37 | + - Browser type and version. |
| 38 | + - Also the driver version, example ChromeDriver version |
| 39 | +
|
| 40 | +2. Steps to reproduce the problem. With more complex problems it is often |
| 41 | + a good idea to create a [short, self contained, correct example (SSCCE)] |
| 42 | + (http://sscce.org). |
| 43 | +
|
| 44 | +3. Possible error message and traceback. |
| 45 | +
|
| 46 | +Notice that all information in the issue tracker is public. Do not include |
| 47 | +any confidential information there. |
| 48 | +
|
| 49 | +Enhancement requests |
| 50 | +~~~~~~~~~~~~~~~~~~~~ |
| 51 | +
|
| 52 | +Describe the new feature and use cases for it in as much detail as possible. |
| 53 | +Especially with larger enhancements, be prepared to contribute the code |
| 54 | +in form of a pull request as explained below or to pay someone for the work. |
| 55 | +Consider also would it be better to implement this functionality as a separate |
| 56 | +tool outside the core framework. |
| 57 | +
|
| 58 | +Code contributions |
| 59 | +------------------ |
| 60 | +
|
| 61 | +If you have fixed a bug or implemented an enhancement, you can contribute |
| 62 | +your changes via GitHub's pull requests. This is not restricted to code, |
| 63 | +on the contrary, fixes and enhancements to documentation_ and tests_ alone |
| 64 | +are also very valuable. |
| 65 | +
|
| 66 | +Choosing something to work on |
| 67 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 68 | +
|
| 69 | +Often you already have a bug or an enhancement you want to work on in your |
| 70 | +mind, but you can also look at the [issue tracker] |
| 71 | +(https://github.com/robotframework/Selenium2Library/issues) to find bugs and |
| 72 | +enhancements submitted by others. The issues vary significantly in complexity |
| 73 | +and difficulty, so you can try to find something that matches your skill level |
| 74 | +and knowledge. |
| 75 | +
|
| 76 | +Pull requests |
| 77 | +~~~~~~~~~~~~~ |
| 78 | +
|
| 79 | +On GitHub pull requests are the main mechanism to contribute code. They |
| 80 | +are easy to use both for the contributor and for person accepting |
| 81 | +the contribution, and with more complex contributions it is easy also |
| 82 | +for others to join the discussion. Preconditions for creating a pull |
| 83 | +requests are having a [GitHub account](https://github.com/), |
| 84 | +installing [Git](https://git-scm.com) and forking the |
| 85 | +[Selenium2Library project] |
| 86 | +(https://github.com/robotframework/Selenium2Library). |
| 87 | +
|
| 88 | +GitHub has good articles explaining how to |
| 89 | +[set up Git](https://help.github.com/articles/set-up-git/), |
| 90 | +[fork a repository](https://help.github.com/articles/fork-a-repo/) and |
| 91 | +[use pull requests](https://help.github.com/articles/using-pull-requests) |
| 92 | +and we do not go through them in more detail. We do, however, |
| 93 | +recommend to create dedicated branches for pull requests instead of creating |
| 94 | +them based on the master branch. This is especially important if you plan to |
| 95 | +work on multiple pull requests at the same time. |
| 96 | +
|
| 97 | +Coding conventions |
| 98 | +~~~~~~~~~~~~~~~~~~ |
| 99 | +
|
| 100 | +Selenium2Library uses the general Python code conventions defined in [PEP-8] |
| 101 | +(https://www.python.org/dev/peps/pep-0008/). In addition to that, we try |
| 102 | +to write [idiomatic Python] |
| 103 | +(http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html) |
| 104 | +and follow the [SOLID principles] |
| 105 | +(https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)) with all |
| 106 | +new code. An important guideline is that the code should be clear enough that |
| 107 | +comments are generally not needed. |
| 108 | +
|
| 109 | +Docstrings should be added to public keywords but are not generally needed in |
| 110 | +internal code. When docstrings are added, they should follow [PEP-257] |
| 111 | +(https://www.python.org/dev/peps/pep-0257/). See [Documentation](#documentation) |
| 112 | +section below for more details about documentation syntax, generating docs, etc. |
| 113 | +
|
| 114 | +We are pretty picky about using whitespace. We use blank lines and whitespace |
| 115 | +in expressions as dictated by [PEP-8](https://www.python.org/dev/peps/pep-0008/) |
| 116 | +, but we also follow these rules: |
| 117 | +
|
| 118 | +- Indentation using spaces, not tabs. |
| 119 | +- No trailing spaces. |
| 120 | +- No extra empty lines at the end of the file. |
| 121 | +- Files must end with a newline. |
| 122 | +
|
| 123 | +The above rules are good with most other code too. Any good editor or IDE |
| 124 | +can be configured to automatically format files according to them. |
| 125 | +
|
| 126 | +Documentation |
| 127 | +~~~~~~~~~~~~~ |
| 128 | +
|
| 129 | +With new features or enhancements adequate documentation is as important as the |
| 130 | +actual functionality. Different documentation is needed depending on the issue. |
| 131 | +
|
| 132 | +The main source of documentation should be placed in to the library and |
| 133 | +individual keywords. But enhancing the internal [wiki] |
| 134 | +(https://github.com/robotframework/Selenium2Library/wiki) or other documentation |
| 135 | +is equally important. |
| 136 | +
|
| 137 | +- Other keywords and sections in the library introduction can be referenced |
| 138 | + with internal links created with backticks like ```Example Keyword``` |
| 139 | +
|
| 140 | +- When referring to arguments, argument names must use in inline code style |
| 141 | + created with double backticks like ````argument````. |
| 142 | +
|
| 143 | +- Examples are recommended whenever the new keyword or enhanced functionality is |
| 144 | + not trivial. |
| 145 | +
|
| 146 | +- All new enhancements or changes should have a note telling when the change |
| 147 | + was introduced. Often adding something like ``New in Selenium2Libray 1.8.`` |
| 148 | + is enough. |
| 149 | +
|
| 150 | +Keyword documentation can be easily created using `<doc/generate.py>`_ |
| 151 | +script. Resulting docs should be verified before the code is committed. |
| 152 | +
|
| 153 | +Tests |
| 154 | +~~~~~ |
| 155 | +
|
| 156 | +When submitting a pull request with a new feature or a fix, you should |
| 157 | +always include tests for your changes. These tests prove that your changes |
| 158 | +work, help prevent bugs in the future, and help document what your changes |
| 159 | +do. Depending an the change, you may need `acceptance tests`_, `unit tests`_ |
| 160 | +or both. |
| 161 | +
|
| 162 | +Make sure to run all of the tests before submitting a pull request to be sure |
| 163 | +that your changes do not break anything. If you can, test in multiple |
| 164 | +browsers and versions (Firefox, Chrome, IE, etc). Pull requests are also |
| 165 | +automatically tested on `continuous integration`_. |
| 166 | +
|
| 167 | +Acceptance tests |
| 168 | +~~~~~~~~~~~~~~~~ |
| 169 | +
|
| 170 | +Most of Selenium2Library's testing is done using acceptance tests that |
| 171 | +naturally use Robot Framework itself for testing. Every new functionality |
| 172 | +or fix should generally get one or more acceptance tests. See |
| 173 | +[Unit and acceptance tests] |
| 174 | +(https://github.com/robotframework/Selenium2Library/blob/master/BUILD.rst#unit-and-acceptance-tests>) |
| 175 | +for more details about creating and executing them. |
| 176 | +
|
| 177 | +Unit tests |
| 178 | +~~~~~~~~~~ |
| 179 | +
|
| 180 | +Unit tests are great for testing internal logic and should be added when |
| 181 | +appropriate. For more details see [Unit and acceptance tests] |
| 182 | +(https://github.com/robotframework/Selenium2Library/blob/master/BUILD.rst#unit-and-acceptance-tests>). |
| 183 | +
|
| 184 | +Continuous integration |
| 185 | +~~~~~~~~~~~~~~~~~~~~~~ |
| 186 | +
|
| 187 | +Selenium2Library's continuous integration (CI) servers are visible through |
| 188 | +https://travis-ci.org/robotframework/Selenium2Library. They automatically |
| 189 | +test all new pull request to the repository with Firefox on Python 2.6 |
| 190 | +and 2.7. |
| 191 | +
|
| 192 | +Finalizing pull requests |
| 193 | +~~~~~~~~~~~~~~~~~~~~~~~~ |
| 194 | +
|
| 195 | +Once you have code, documentation and tests ready, it is time to finalize |
| 196 | +the pull request. |
| 197 | +
|
| 198 | +AUTHORS.txt |
| 199 | +~~~~~~~~~~~ |
| 200 | +
|
| 201 | +If you have done any non-trivial change and would like to be credited, |
| 202 | +add yourself to [AUTHORS.txt](TOBEDEFINED) file. |
| 203 | +
|
| 204 | +Resolving conflicts |
| 205 | +~~~~~~~~~~~~~~~~~~~ |
| 206 | +
|
| 207 | +Conflicts can occur if there are new changes to the master that touch the |
| 208 | +same code as your changes. In that case you should [sync your fork] |
| 209 | +(https://help.github.com/articles/syncing-a-fork>) and [resolve conflicts] |
| 210 | +(https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line) |
| 211 | +to allow for an easy merge. |
| 212 | +
|
| 213 | +The most common conflicting file is the aforementioned [AUTHORS.txt](TOBEDEFINED) |
| 214 | +, but luckily fixing those conflicts is typically easy. |
| 215 | +
|
| 216 | +Squashing commits |
| 217 | +~~~~~~~~~~~~~~~~~ |
| 218 | +
|
| 219 | +If the pull request contains multiple commits, it is recommended that you |
| 220 | +squash them into a single commit before the pull request is merged. |
| 221 | +See [Squashing Github pull requests into a single commit] |
| 222 | +(http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit) |
| 223 | +article for more details about why and how. |
| 224 | +
|
| 225 | +Squashing is especially important if the pull request contains lots of |
| 226 | +temporary commits and changes that have been later reverted or redone. |
| 227 | +Squashing is not needed if the commit history is clean and individual |
| 228 | +commits are meaningful alone. |
0 commit comments