= Contribution guidelines

These guidelines instruct how to submit issues and contribute code or
documentation to the
https://github.com/robotframework/RIDE[RIDE]. There are also many other projects in the larger
http://robotframework.org[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
https://forum.robotframework.org/c/tools/ride/21[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 https://opensource.guide/[Open Source Guides] first.

== Submitting issues

Bugs and enhancements are tracked in the
https://github.com/robotframework/RIDE/issues[issue tracker].
If you are unsure if something is a bug or is a feature worth
implementing, you can first ask on link:https://forum.robotframework.org/c/tools/ride/21/[RIDE-users] 
(#RIDE on irc.freenode.net), or on
https://robotframework-slack-invite.herokuapp.com[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.

=== Reporting bugs


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 http://sscce.org[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.

=== Enhancement requests

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.

== Code contributions

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
link:#documentation[documentation] and link:#tests[tests] alone are also
very valuable.

=== Choosing something to work on

Often you already have a bug or an enhancement you want to work on in
your mind, but you can also look at the link:[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: https://github.com/robotframework/RIDE/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+[good first issue] or https://github.com/robotframework/RIDE/labels/help_wanted[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.

=== Pull requests

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 https://github.com/[GitHub account], installing
https://git-scm.com[Git] and forking the link:[Robot Framework project].

GitHub has good articles explaining how to
https://help.github.com/articles/set-up-git/[set up Git],
https://help.github.com/articles/fork-a-repo/[fork a repository] and
https://help.github.com/articles/using-pull-requests[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.

=== Coding conventions

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 https://wxpython.org[wxPython] in particular by exploring its demo.

==== General guidelines

RIDE uses the general Python code conventions defined in
https://www.python.org/dev/peps/pep-0008/[PEP-8]. In addition to that,
we try to write
http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html[idiomatic
Python] and follow the
https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)[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.6). RIDE's code 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.

==== Line length

Maximum line length with Python code, including docstrings and comments,
is 100 characters. This is also what
https://pypi.org/project/black/[Black] uses by default and
https://black.readthedocs.io/en/stable/the_black_code_style.html#line-length[their
documentation] explains why. Notice that we do not have immediate plans
to actually take Black into use but we may consider that later.


==== Whitespace

We are pretty picky about using whitespace. We follow link:[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

Docstrings should be added to public APIs, but they are not generally
needed in internal code. When docstrings are added, they should follow
https://www.python.org/dev/peps/pep-0257/[PEP-257]. See
link:#api-documentation[API documentation] section below for more
details about documentation syntax, generating API docs, etc.

=== Documentation

With new features adequate documentation is as important as the actual
functionality. Different documentation is needed depending on the issue.

=== RIDE's Wiki

https://github.com/robotframework/RIDE/wiki[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.


== Tests

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.

=== Executing changed code

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

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

=== Acceptance tests

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 https://rainmanwy.github.io/robotframework-SikuliLibrary/doc/SikuliLibrary.html[SikuliLibrary].
Please contact us via Slack, if you would like to join this testing group.


== Finalizing pull requests

Once you have code, documentation and tests ready, it is time to
finalize the pull request.

=== Acknowledgments

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.

=== Resolving conflicts


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.


==== For more info you can read `README.adoc`