Technical hints for contributors

How to contribute

1. Fork the repository

Forking a repository on github means creating a clone of a repository on github. Simply click on “Fork” in the TRAL repos TRAL repository once you have a Github account.

2. Clone the repository from your fork

From the command line, create a clone of your fork:

git clone https://github.com/<YOUR_USER_NAME>/tral

3. Create your feature branch

If you use git-flow, start a new feature:

git-flow start feature <YOUR_FEATURE>

Otherwise, create a new branch as follows:

git checkout -b feature/<YOUR_FEATURE>

Next, add the necessary changes and commit them:

git add <CHANGED_FILE>
git commit -m 'CHANGED_FILE: DESCRIPTION OF YOUR CHANGES’

4. Push your feature branch to your github fork

git push origin feature/<FEATURE_NAME>

5. Create a pull request.

Create the pull request online on github. For this, go to your github page and click on “Pull Request”.

https://github.com/<YOUR_USER_NAME>/tral

Do a pull request on the develop branch of acg-team/tral.

base fork: acg-team/tral
base: develop

How to contribute to the homepage

Check out the current version of the TRAL homepage as follows:

git clone --single-branch -b gh-pages https://<your_git_name>@github.com/acg-team/tral.git

How to test a package on pypitest

Install the package from pypitest as follows:

pip install -i https://testpypi.python.org/pypi

How to use Pypi

This documentation summarizes the steps to a new release of TRAL.

Version number updates

  • README.md

  • tral/__init__.py

  • docs/conf.py

Try testpypi

cd ~
swap .pypirc_testpypi .pypirc

cd [TRAL directory]
python setup.py sdist upload -r pypitest

cd ~
swap .pypirc_testpypi .pypirc

cd [Installation test directory]
pip install -i https://testpypi.python.org/pypi tral

Release Process

1. Bump Version Number

Change version in:

  • README.md

  • tral/__init__.py

  • docs/conf.py

2. Test

Run all tests again.

cd tral/tral
pytest

Make sure, that pytest is installed in the virtual environment.

3. Rebuild docs

The documentation is build with sphinx. Check if all external links are correct, update and commit if necessary.

Checkout branch develop:

git checkout develop

Move into ‘./tral/docs’ directory and build the docs:

cd tral/docs
make html

The new docs are stored in ./tral/docs/_build/html/. Copy them outside the git repository and checkout to the gh-pages branch.

cp -r tral/docs/_build/html ~
git checkout gh-pages

Move the fresh build docs to gh-pages:

mv -r ~/html/* ./tral/docs

[CHECK IF THIS IS CORRECT]

Check the updated docs online (synchronizes automatically) at acg-team.github.io.

4. Build a python wheel

git checkout develop
python setup.py sdist bdist_wheel

5. Create a git tag

-s requires a gpg key.

git tag -s -a <VERSION>

6. Upload to PyPi test

Check the wheel and git tag:

twine check dist/*; git verify-tag <VERSION>

Upload to PyPi test platform first:

twine upload --repository testpypi dist/*

7. Git Release

git checkout develop
git push; git push --tags

8. Upload to PyPi

twine upload dist/*

8. Build docker container

Create Github.com Token and login your docker instance:

cat TOKEN.txt | docker login https://docker.pkg.github.com -u USERNAME --password-stdin

We encountered issues if not all tral related docker container and images were stopped and removed. Continue then with building a new docker image with the new release:

sudo docker build -t docker.pkg.github.com/acg-team/tral/tral_docker:<VERSION> -t docker.pkg.github.com/acg-team/tral/tral_docker:latest -f tral/docker/Dockerfile --no-cache
sudo docker push docker.pkg.github.com/acg-team/tral/tral_docker:latest

10. Prepare repository for further development

Increment version in __init_.py from i.e. 2.0.0 to 2.0.1.dev0.