Developer’s Guide

Setup

First, you should clone the GitHub repository and checkout the develop branch.

git clone git@github.com:adopy/adopy.git
cd adopy
git checkout develop

To manage a virtual environment for development, we uses poetry. Pipfile on the repository describes which packages to install for a virtual environment. You can create a virtual environment by running the command below:

# Install the virtual environment defined in the pyproject.toml
poetry install

Now you can activate the installed virtual environment. Code blocks on later sections assume this environment activated.

# Activate the virtual environment
poetry shell

Writing documentation

The documentation is generated based on Sphinx. Sphinx provides its rich features using reStructuredText files for its markup language. Thus, to get benefits from Sphinx, this documentation website is created from reStructuredText sources on /docs/source directory.

Basically, the official website (https://adopy.org) is automatically generated from documentations in the Python codes on /adopy and reStructuredText files (*.rst) on /docs/source, in master branch of the repository. In other words, the documentations shown in the website are for the stable version of ADOpy in master branch.

Using sphinx-autobuild, you can build the documentation and test it by yourself. It can run a web server for documentation on http://localhost:8000, as described below.

# Go to /docs directory
cd docs

# On Windows
livehtml.bat

# On macOS or Linux
make livehtml

Branch management

The basic process of ADOpy development follows the Gitflow workflow by Vincent Driessen, which holds two main branches: master and develop. Only an exception is that we use feature/*, hotfix/*, or release/* instead of feature-*, hotfix-* or release-*. There are a bunch of great resources about Gitflow and we require you to read at least one of them before proceeding.

• The original post by Vincent Driessen

• Gitflow Workflow - Atlassian Git Tutorial

• Read Git Flow | Leanpub

• git-flow cheatsheet

• Managing your Git branches with Git Flow | Zell Liew

• Using git-flow to automate your git branching workflow

If you want to contribute to ADOpy, you can start with forking the ADOpy repository in the GitHub. Before you start writing a code, please make a new issue for what you want to do. Then, following the Gitflow, you should make a proper branch to work with. We only allow feature branches for who is not authorized. If your job is done, you can make a pull request on the ADOpy repository and let us review it before merging it.