Contributing to Asynch¶
You are here to help on Asynch? Awesome, feel welcome and read the following sections in order to know what and how to work on something. If you get stuck at any point you can create a ticket on GitHub.
Contributing to development¶
If you want to deep dive and help out with development on Read the Docs, then first get the project installed locally according to the Installation instruction. After that is done we suggest you have a look at tickets in our issue tracker that are labelled Good First Bug. These are meant to be a great way to get a smooth start and won’t put you in front of the most complex parts of the system.
If you are up to more challenging tasks with a bigger scope, then there are a set of tickets with a Enhancement tag. These tickets have a general overview and description of the work required to finish. If you want to start somewhere, this would be a good place to start. That said, these aren’t necessarily the easiest tickets. They are simply things that are explained. If you still didn’t find something to work on, search for the Sprintable label. Those tickets are meant to be standalone and can be worked on ad-hoc.
When contributing code, then please follow the standard Contribution Guidelines set forth at contribution-guide.org.
Keeping the documentation updated¶
Whenever an update in the code adds, changes or removes elements that affect the user experience (i.e.: changes in input forcing formats, existing hlm models, global file format, etc ), it is expected from the developer to perform the respective updates in the Read the Docs documentation.
Here are some tips and explanations regarding the documentation process.
Documentation structure¶
The documentation publicly available at http://asynch.readthedocs.io
is hosted by Read the Docs in a project that is maintained by the same maintainers of Asynch.
This documentation is written in reStructuredText
formatting language (*.rst files) and uses Sphinx with Read the Docs libraries for compilation purposes. All the files are relevant for the documentation are located in the doc/
folder.
Working locally¶
A desktop environment can be set up to compile the documentation locally. This approach is good for debugging the result before publishing it publicly.
For setting up the environment, you will have to install Read the Docs on your machine in a separated virtual Python environment.
Ensure git 1.5 or higher, Python 3.6 or higher, and both Python virtualenv and virtualenvwrapper are installed. If using Windows, ensure Python virtualenvwrapper-win and cmder are also installed (use cmder to perform the following command operations).
Create a virtual environment for compiling Read the Docs documentations:
mkvirtualenv readthedocs
If your command session does not activate the newly created virtual environment automatically, activate it:
workon readthedocs
Navigate to this virtualenv directory:
cd [USER_HOME]\Env\readthedocs\
Checkout Read the Docs into a new folder and enter there:
mkdir checkouts
cd checkouts
git clone https://github.com/rtfd/readthedocs.org.git
cd readthedocs.org\
Install all requirements for Read The Docs:
pip install -r requirements.txt
or:
python -m pip install -r requirements.txt
Navigate to the docs
directory of the local clone of Asynch repository:
cd [ASYNCH]\docs\
Perform the changes you want in the .srt
files within this folder. After that, compile using the command:
make html
Note
1-) When compiling, ensure you are still working on the readthedocs virtual Python environment;
2-) When compiling, some Python packages may be required. Be prepared to perform pip installs;
3-) The command ‘make’ also works on Windows when runned within cmder.
Access the results opening the file [ASYNCH]/docs/.build/html/index.html
with a web browser.
This mini tutorial was adapted from here.
Publishing¶
Everytime a git push
or pull request
is performed into the master
or develop
branches in the Git Hub repository, or on a branch that creates a new tag
, the Read the Docs server reads, compiles and publishes the documentation online.
This connection between Git Hub and Read the Docs is established through the so called webhooks. The official Asynch Git Hub account has a webhook that triggers the compiling steps from the Read the Docs server.
Managing releases¶
Once you are happy with your changes in the develop
branch and ran a couple of test simulations, here is the procedure to release a new version x.y.z
(e.g. 1.5.0
):
Branch¶
Create a branch for the release following the release-x.y.z
naming scheme and semantic versionning rules :
git branch release-x.y.z
Edit¶
Edit the release notes (doc/release_notes.rst
).
Edit configure.ac
to bump the version number:
AC_INIT([asynch], [x.y.z], [samuel-debionne@uiowa.edu])
Commit your changes.
git add configure.ac doc/release_notes.rst
git commit -m "Bump version number to x.y.z"
git push
Generate the tarball¶
In a new empty folder, run the following commands to clone the repository, generate the configure script and the tarball.
git clone https://github.com/Iowa-Flood-Center/asynch.git
git checkout release-x.y.z
autoreconf -i
mkdir build && cd build
export TAR_OPTIONS="--owner=0 --group=0 --numeric-owner"
../configure
make dist
That should generate a release-x.y.z.tar.gz
that needs to be tested.
Test the tarball¶
In a new empty folder, follow the instructions in Installing the package:
tar xf release-x.y.z.tar.gz
cd release-x.y.z
mkdir build && cd build
../configure CFLAGS="-O2 -DNDEBUG"
make
make check
make install
Adjust the release branch if there is any problem with the build (e.g. missing header file).
Release on Github¶
Merge the release branch release-x.y.z
to master
. The easiest way is to submit a new Pull Request. The base branch should be Iowa-Flood-Center/asynch
/ master
and the compare branch Iowa-Flood-Center/asynch
/ release-x.y.z
.
Review your Pull Request, or better let someone else do the review. If everything looks good, and you have Travis CI’s blessing, do a “Merge and Squash”.
You can safely delete the release branch at this point.
Click on “Draft a new release” in Releases:
Field | Value |
---|---|
Tag version | vx.y.z (v1.5.0) |
Release title | Pick a city in Iowa |
Description | A short version of the release notes |
Attach the tarball that was generated in the previous step. This is usefull because the tarball does not require the target computer to have autotools installed.
Ready? “Publish Release”! Every followers of the repo get notified of the new version. Good job!