Skip to content

Latest commit

 

History

History
158 lines (116 loc) · 6.47 KB

CONTRIBUTING.rst

File metadata and controls

158 lines (116 loc) · 6.47 KB
Raw

Feedback and Contribution

We welcome any contribution via ROSS' issue tracker. These include bug reports, problems on the documentation, feedback, enhancement proposals etc. The issue tracker can also be used for questions and further information since the project does not use a mailing list.

Version-control system: Git

Git is a version control system (VCS) for tracking changes in code during software development. To download the ROSS source code and contribute to its development, you need Git installed in your machine. Refer to the Git website and follow the instructions to download and install it. Once you have Git installed, you will be able to follow the instructions in How to contribute to ROSS using git, which explains how to download and contribute to ROSS.

Code style: Black

To format our code we use Black, which is the "uncompromising Python code formatter". You can configure your development environment to use Black before a commit. More information on how to set this is given at Black's documentation.

Documentation

We use sphinx to generate the project's documentation. We keep the source files at ~/ross/docs, and we keep the html files used to build the website in a separate repository. The website tracks the documentation for the released version with the following procedure:

  1. Travis runs the deploy_docs.sh file ('after_success' phase);
  2. The deploy_docs script checks if the branch being updated has the same name as the current released ROSS' version (ross.__version__);
  3. If 2 is True, the script will build the docs for that branch and push to the ross-website repo.

So, if you want to modify the documentation website, modify the source files and then make a pull request to the branch named as the current released version.

If you want to test the documentation locally:

  • Install pandoc, which is needed to convert the notebook files;

  • Clone the ross-website to <some-path>/ross-website/html:

    git clone https://github.com/ross-rotordynamics/ross-website <some-path>/ross-website/html

  • From the docs source directory </ross/docs/> run sphinx:

    make html BUILDDIR=<some-path>/ross-website

  • Go to the builddir and run a html server:

    cd <some-path>/ross-website/html
python -m http.server

After that you can access your local server (http://0.0.0.0:8000/) and see the generated docs.

How to contribute to ROSS using git

To use git to contribute to ROSS project, follow the steps below: For Windows users: commands provided here can be executed using Git Bash instead of Git GUI.

Step 1: Make your copy (fork) of ROSS

Go to https://github.com/ross-rotordynamics/ross In the top-right corner of the page, click Fork, to fork it to your GitHub account.

From the command line:

git clone https://github.com/your-user-name/ross.git
cd ross
git remote add upstream https://github.com/ross-rotordynamics/ross.git

Step 2: Keep in sync with changes in ROSS

Setup your local repository, so it pulls from upstream by default:

git config branch.master.remote upstream
git config branch.master.merge refs/heads/master

This can also be done by editing the config file inside your ross/.git directory. It should look like this:

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = https://github.com/your-user-name/ross.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[remote "upstream"]
        url = https://github.com/ross-rotordynamics/ross.git
        fetch = +refs/heads/*:refs/remotes/upstream/*
        fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*
[branch "master"]
        remote = origin
        merge = refs/heads/master

The part fetch = +refs/pull/*/head:refs/remotes/upstream/pr/* will make pull requests available.

Step 3: Set up development environment

To set up a development environment you can create a conda environment or a virtualenv:

python3 -m venv env
. env/bin/activate
# or "env\Scripts\activate" on Windows

and then install ROSS in editable mode with development dependencies:

pip install -e ".[dev]"

Step 4: Make a new feature branch

git fetch upstream
git checkout -b my-new-feature upstream/master

Step 5: Testing the code

We use pytest to test the code. Unit tests are placed in the ~/ross/ross/tests folder. We also test our docstrings to assure that the examples are working. If you want to run all the tests you can do it with (from the ~/ross/ross folder):

pytest

Code is only merged to master if tests pass. This is checked by services such as Travis CI and Appveyor, so make sure tests are passing before pushing your code to github.

Step 6: Push changes to your git repository

After a complete working set of related changes are made:

git add modified_file
git commit
git push origin my-new-feature

The following blog posts have some good information on how to write commit messages:

A Note About Git Commit Messages

On commit messages

Step 7: Push changes to the main repo

To create a Pull Request (PR), refer to the github PR guide.

Making new releases

To make a new release we need only to create a tag using git and push to GitHub:

git tag <version number>
git push upstream --tags

Pushing the new tag to the GitHub repository will start a new build on Travis CI. If all the tests succeed, Travis will upload the new package to PyPI (see the deploy command on .travis.yml).