Develop and contribute¶

Welcome to the RAMP team. We are always happy to have new RAMP developers.

You can contribute to this code by making a Pull Request on Github. Please, make sure that your code is coming with unit tests to ensure full coverage and continuous integration in the API.

Install for development¶

To install RAMP please follow install guideline making sure that you use the make inplace option to install RAMP in developer mode.

Prepare database engine¶

Testing RAMP requires a database cluster, you need to create it similarly as described in create database section.

If you haven’t done so already create the Postgres database cluster using the command:

~ $ initdb postgres_dbs

and then start it with:

~ $ pg_ctl -D postgres_dbs -l logfile start

Within your database cluster postgres database is created automatically. pytest will use it to make and then drop the test engine. But it needs to know who is the owner of your postgres database and therefore you need to inform RAMP tests about this. To do this, open the db_engine.yml file located in the ramp-board directory. It should look as follows:

db_owner: postgres

You need to change <postgres> to the owner of the postgres database.

If you don’t know who is the owner of your postgres database you can find it out by typing in your terminal:

~ $ psql -l

This command will list all of your databases along with their owners.

Test¶

In order to run your tests please create a test conda environment (you will need to do that only once):

~ $ conda env create -f ci_tools/environment_iris_kit.yml

Also, before running the tests make sure your Postgres database cluster has been started. You can always start it using the command:

~ $ pg_ctl -D postgres_dbs -l logfile start

where postgres_dbs is the database cluster you created in the previous steps.

In addition, you might want to start an SMTP server to run all the tests. If you don’t run the server, some of the tests will fail because they cannot be run. To launch the server, execute the following command:

~ $ python -m smtpd -n -c DebuggingServer localhost:8025 &

You are now ready to run the tests. You can do so using pytest from the root ramp-board directory:

~ $ pytest -vsl .

The above will only work when the packages were installed in development mode. In the other case, you can test the individual packages with:

~ $ pytest -vsl --pyargs ramp_utils ramp_database ramp_frontend ramp_engine

How to contribute¶

This guide is adapted from scikit-learn contribution guide.

Forking RAMP¶

The preferred way to contribute to RAMP is to fork the ramp-board repository on GitHub:

To fork the ramp-board repository click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub server.

Clone this copy to your local disk:

$ git clone git@github.com:YourLogin/ramp-board.git
$ cd ramp-board

Create a branch (called ‘my-feature’ below) to hold your changes:
```
$ git checkout -b my-feature
```
and start making changes.

Note

Never work in the master branch!

Work on this copy on your computer using Git to do the version control. When you’re done editing, do:
```
$ git add <modified_files>
$ git commit
```
to record your changes in Git, then push them to GitHub with:
```
$ git push -u origin my-feature
```

Finally, go to the web page of your fork of the ramp-board repo, and click ‘Pull request’ to send your changes to the maintainers for review. This will send an email to the committers.

If any of the above seems like magic to you, then look up Git documentation on the web.

Contributing Pull Requests¶

It is recommended to check that your contribution complies with the following rules before submitting a pull request:

Follow the coding-guidelines as for scikit-learn.
When applicable, use the validation tools and other code in the ramp_utils subpackage.
If your pull request addresses an issue, please use the title to describe the issue and mention the issue number in the pull request description to ensure a link is created to the original issue.
All public methods should have informative docstrings with sample usage presented as doctests when appropriate.
Please prefix the title of your pull request with [MRG] if the contribution is complete and should be subjected to a detailed review. Incomplete contributions should be prefixed [WIP] to indicate a work in progress (and changed to [MRG] when it matures). WIPs may be useful to: indicate you are working on something to avoid duplicated work, request broad review of functionality or API, or seek collaborators. WIPs often benefit from the inclusion of a task list in the PR description.
All other tests pass when everything is rebuilt from scratch. On Unix-like systems, check with (from the toplevel source folder):
```
$ make
```
Documentation and high-coverage tests are necessary for enhancements to be accepted.
At least one paragraph of narrative documentation with links to references in the literature (with PDF links when possible) and the example.

You can also check for common programming errors with the following tools:

Code with good unittest coverage (at least 80%), check with:
```
$ pip install pytest pytest-cov
$ pytest -vsl .
```
No flake8 warnings (which includes pep8 and pyflakes), check with:
```
$ pip install flake8
$ flake8 path/to/module.py
```

Filing bugs¶

We use Github issues to track all bugs and feature requests; feel free to open an issue if you have found a bug or wish to see a feature implemented.

It is recommended to check that your issue complies with the following rules before submitting:

Verify that your issue is not being currently addressed by other issues or pull requests.
Please ensure all code snippets and error messages are formatted in appropriate code blocks. See Creating and highlighting code blocks.

Please include your operating system type and version number, as well as your Python, scikit-learn, numpy, and scipy versions. This information can be found by running the following code snippet:

python
import platform; print(platform.platform())
import sys; print("Python", sys.version)
import numpy; print("NumPy", numpy.__version__)
import scipy; print("SciPy", scipy.__version__)
import sklearn; print("Scikit-Learn", sklearn.__version__)

Please include a reproducible code snippet or link to a gist. If an exception is raised, please provide the traceback.

Documentation¶

We are glad to accept any sort of documentation: function docstrings, reStructuredText documents (like this one), tutorials, etc. reStructuredText documents live in the source code repository under the doc/ directory.

You can edit the documentation using any text editor and then generate the HTML output by typing make html from the doc/ directory. Alternatively, make can be used to quickly generate the documentation without the example gallery. The resulting HTML files will be placed in _build/html/ and are viewable in a web browser. See the README file in the doc/ directory for more information.

For building the documentation, you will need

sphinx,

sphinx_rtd_theme,

numpydoc,

graphviz,

eralchemy,

sphinx-click,

matplotlib.

When you are writing documentation, it is important to keep a good compromise between mathematical and algorithmic details, and give intuition to the reader on what the algorithm does. It is best to always start with a small paragraph with a hand-waving explanation of what the method does to the data and a figure (coming from an example) illustrating it.

Minor release process¶

The following explain the main steps to release ramp-board:

Run bumpversion release. It will remove the dev0 tag.
Commit the change git commit -am "bumpversion 0.<version number>.0" (e.g., git commit -am "bumpversion 0.5.0").
Create a branch for this version (e.g., git checkout -b 0.<version number>.X).
Push the new branch into the upstream remote ramp-board repository.
Create a GitHub release by clicking ‘Draft a new release’ here. Copy the release notes from whats_new.
Change the symlink in the ramp-docs repository such that stable points to the latest release version, i.e, 0.<version number>. To do this, clone the ramp-docs repository, cd into ramp-docs/ramp-board/ then run unlink stable, followed by ln -s 0.<version number> stable. To check that this was performed correctly, ensure that ramp-board/stable has the new version number.
cd back into the ramp-board code repository and ensure you are in the release branch (e.g., branch 0.5.X). Remove unnecessary files with make clean-dist then push on PyPI with make upload-pypi.
Switch to master branch and run bumpversion minor, commit and push on upstream.
Create a GitHub release by clicking on ‘Draft a new release’ here. ‘Tag version’ should be the latest version number (e.g., 0.5.0), ‘Target’ should be the branch for that minor version (e.g., 0.5.X) and ‘Release title’ should be ‘Version <release version>’ (e.g., ‘Version 0.5.0’). Detail changes in this release, using what’s in the doc/whats_new/ file for the latest release.
Add a new v0.<version number>.rst file in doc/whats_new/ and .. include:: this new file in doc/whats_new.rst.

Note that the steps 4, 5 and 7 should be performed while in the release

branch, e.g. branch 0.5.X.

Patch/bug fix release process¶

Checkout the tag for the last minor release, e.g., git checkout 0.5.X. note: X is part of the name, not a number to substitute. note2: you can type git fetch --all --tags to fetch available tags.
There are two ways to continue. If you only want to release a couple of commits we recommend that you go with ‘3a’, if you want to release many commits ‘3b’ would be easier.

3a: release only a few commits

Find the commit(s) hash of the bug fix commit you wish to back port using git log.
Append the bug fix commit(s) to the branch using git cherry-pick <hash>.

3b: release multiple commits

checkout the 0.5.X branch: git checkout -b release-0.5.<number> master where ‘number’ is the number of your bug release.
commit your desired changes by typing: git rebase -i master. You should now see the list of all the commits since the last release. Indicate which commits you want to release by typing ‘pick’ on their lefthand side, and ‘drop’ if you do not want to keep it. Make sure to drop the commit with previous bumpversion. It’s useful to have a copy of the git rebase -i log in the PR to help others understand what’s included.
make a PR to the release branch. Once it is merged continue to the next step.

Bump the version number with bumpversion patch. This will bump the patch version, for example from 0.5.0 to 0.5.1.dev0.
Mark the current version as a release version (as opposed to ‘dev’ version) with bumpversion release --allow-dirty. It will bump the version, for example from 0.5.1.dev0 to 0.5.1.
Commit the changes with git commit -am 'bumpversion <new version>'.
Push the changes to the release branch in upstream, e.g. git push <upstream remote> <release branch>. For minor version 0.5 ‘release branch’ would be ‘0.5.X’
Remove unnecessary files with make clean-dist then push on PyPI with make upload-pypi (you need to have the rights on PyPI to do so).
Create a GitHub release by clicking ‘Draft a new release’ here. Note down the bug fixes added in the patch.

Note: If you are updating version of ramp on ramp.studio consider reading: those docs.