ro-crate-py is open source software distributed under the Apache License, Version 2.0. Contributions are welcome, but please read this guide first. Submitted contributions are assumed to be covered by section 5 of the license.
Set up Git on your local machine, then fork this repository on GitHub and create a local clone of your fork.
For instance, if your GitHub user name is simleo, you can get a local clone as follows:
$ git clone https://github.com/simleo/ro-crate-py
You can see that the local clone is pointing to your remote fork:
$ cd ro-crate-py
$ git remote -v
origin https://github.com/simleo/ro-crate-py (fetch)
origin https://github.com/simleo/ro-crate-py (push)
To keep a reference to the original (upstream) repository, you can add a remote for it:
$ git remote add upstream https://github.com/researchobject/ro-crate-py
$ git fetch upstream
This allows, among other things, to easily keep your fork synced to the upstream repository through time. For instance, to sync your master branch:
$ git checkout master
$ git fetch -p upstream
$ git merge --ff-only upstream/master
$ git push origin master
If you need help with Git and GitHub, head over to the GitHub docs. In particular, you should be familiar with issues and pull requests.
Contributions can range from fixing a broken link or a typo in the documentation to fixing a bug or adding a new feature to the software. Ideally, contributions (unless trivial) should be related to an open issue. If there is no existing issue or pull request related to the changes you wish to make, you can open a new one.
Make your changes on a branch in your fork, then open a pull request (PR). Please take some time to summarize the proposed changes in the PR's description, especially if they're not obvious. If the PR addresses an open issue, you should link it to the issue.
Currently, documentation consists of a few Markdown files such as this one. Read the Mastering Markdown guide for a quick introduction to the format. Before opening the PR, you can check that the document renders as expected by looking at the corresponding page on the relevant branch in your fork.
ro-crate-py is written in Python. To isolate your development environment from the underlying system, you can use a virtual environment:
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install --upgrade pip
$ pip install -r requirements.txt
For development, it's recommended to install ro-crate-py in editable mode:
pip install -e .
In this way, any changes to the code will be picked up immediately, without the need to reinstall the package.
When you're done with your work, you can deactivate the virtual environment by typing deactivate on your shell.
Before pushing any changes, make sure everything is fine by running the linting and testing commands as explained below.
ro-crate-py uses Flake8 for linting. The configuration is in setup.cfg and it's picked up automatically. If you have a venv directory or any other directory you don't want to be checked by Flake8, use the --exclude option.
pip install flake8
flake8 --exclude venv ./
Testing is done with pytest:
pip install pytest
pytest test
If a test is failing, you can get more information by enabling verbose mode and stdout/stderr dump. For instance:
pytest -sv test/test_write.py::test_remote_uri_exceptions
Ideally, every code contribution should come with new unit tests that add coverage for the bug fix or new feature.
ro-crate-py is currently a fairly simple library that does not require any special infrastructure setup, so virtual environments should be enough for development. However, if you want a higher degree of isolation, you can build the Docker image with:
docker build -t ro-crate-py .
And then run it interactively with:
docker run --rm -it --name ro-crate-py ro-crate-py bash
After your PR has been merged, you can delete the branch used for your changes. You can delete the remote branch from GitHub, by clicking on "Delete branch" in the PR's page. To resync everything, run:
git checkout master
git fetch -p upstream
git merge --ff-only upstream/master
git push origin master
git branch -d <pr_branch_name>