Skip to content

Commit 7cbb77d

Browse files
emanloveemanlove
authored
Merge pull request robotframework#509 from aaltat/CONTRIBUTING_rst
Initial version of CONTRIBUTING.md
2 parents 3f47202 + 4c5a5ed commit 7cbb77d

File tree

1 file changed

+197
-0
lines changed

1 file changed

+197
-0
lines changed

‎CONTRIBUTING.md

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

0 commit comments

Comments
 (0)