Contributing#

Introduction#

OpenAlea is open-source. Everyone is welcome to contribute.

Note

All the packages are separated on two Github pages

the official and stable packages on OpenAlea
the unofficial, WIP and to be reviewed packages on OpenAlea-Incubator

There are many ways to contribute to OpenAlea. The most common ways of contributing are coding or documenting different parts of the project. One may improve documentation which is as much important as improving the code itself. One could also create their own package, see How to contribute.

Another way to contribute to the project is to report bugs ans issues you are facing.

How to contribute#

The main way to contribute is to fork the package repository you are interested in on GitHub.

Note

Remember, the packages are found on different GitHub pages. The following steps describe a tutorial for an OpenAlea package. Make the good changes if you want to use OpenAlea-Incubator packages.

Warning

All proposed changes must follow the OpenAlea development guidelines

Create an account on GitHub if you do not already have one. You will choose your GitHub login <your_login>.
Fork the package repository of your choice (for instance, MTG repository) and click on the ‘Fork’ button near the top of the page. It generates a copy of the repository under your account on the GitHub user account. For more details on how to fork a repository see this guide.

Clone your fork of the package repo from your GitHub account to your local disk

git clone https://github.com/<your_login>/<package_name>.git
cd <package_name>

Create a branch <branch_name> to hold your development changes
```
git checkout -b <branch_name>
```
and start making changes. Always use a feature branch. It’s good practice to never work on the master / main branch!
Note

In the above setup, your origin remote repository points to <your_login>/.git. If you wish to fetch/merge from the main repository instead of your forked one, you will need to add another remote to use instead of origin. It’s good practice to choose the name upstream for it, and the command will be:
```
git remote add upstream https://github.com/openalea/<package_name>.git
```
If the package you chose come from OpenAlea-Incubator, the command will be:
```
git remote add upstream https://github.com/openalea_incubator/<package_name>.git
```
And in order to fetch the new remote and base your work on the latest changes of it you can:
```
git fetch upstream
git checkout -b <your_name> upstream/master
```
Develop the feature on your feature branch on your computer, using Git to do the version control. When you’re done editing, add changed files using git add and then git commit files:
```
git add <modified_files>
git commit -m "description of what you've done"
```
to record your changes in Git, then push the changes to your GitHub account with:
```
git push -u origin <branch_name>
```
Once you’ve finished, you can create a pull request on the corresponding GitHub. Follow these instructions to create a pull request from your fork.

How to make a proper bug report#

The best way to intereact with the OpenAlea packages developers is to use the GitHub issue tracker. You can report bugs, request features or simply ask for help. Each package has its own issue tracker on its GitHub page.

To make a proper bug report, you should follow these steps:

Describe the issue, being as precise as possible.
Provide a minimal code example to reproduce the issue.
Provide the version of the package you are using. Eventually, please also provide the versions of the dependancies.
Show the Error Message you are getting.

If not already available, issue templates are also a good way to provide homogeneous reports to developers. See Github isse templates

Documentation#

You can also contribute to the documentation. If you find some parts that are not explained enough or uncleared, you can complete or improve the documentation.

Once you have forked the package on your device (cf. How to contribute), you have to install Sphinx to generate the HTML output

pip install sphinx

In each package repository, it must be a docs/ directory in which the reStructuredText documents are. You can modify or create these and generate the HTML output in the docs/ directory

make html

Note

If you are creating your own package, you can build the Sphinx environment directly in the docs/ directory

sphinx-quickstart

Once you are finished, you can add, commit and push what you have done on GitHub and then create a pull request (see How to contribute).

As we want all the documentation to look the same way, your Sphinx configuration file conf.py should match the Documentation.`

The theme we are using is the Read the Docs Sphinx Theme. The theme can be installed like this
```
pip install sphinx_rtd_theme
```
Once you’ve installed the theme, write in your conf.py file
```
html_theme = "sphinx_rtd_theme"
```
Then write in the same file
```
html_theme_options = {
         'logo_only': True
}
```
Download the OpenAlea logo and put it your _static directory and then write in your conf.py file
```
html_static_path = ['_static']
html_logo = "_static/openalea_web.svg"
```
Mention the main website “openalea.rtfd.io”

Contributing#

Introduction#

How to contribute#

How to make a proper bug report#

Documentation#

This Page