WikiPrint - from Polar Technologies


The aim of this section will be to explain the process we follow to contribute to the development of the DRM4G.

We use something similar to a ?gitflow workflow. Internally we synchronize our work with GitBucket, which is what will be considered as the central repository of the Santander Meteorology Group.

Necessary Steps

There are a lot of tutorials showing how to use git, including our own, but this is more straightforward explanation on how to get started.

In Linux operating systems:

git init  #to initialize an empty Git repository
git remote add origin #to make your local repository point to the remote repository in GitBucket
git checkout master #to create a local repository of the master branch
git checkout develop #to create a local repository of the develop branch

If you want to see the changes your doing, check the file ".git/config" under your repository directory.

With this, you will now have DRM4G's source code at your disposal.

From here you should follow our gitflow and create branches for every new feature you'd like to include to the DRM4G.

Testing the DRM4G

Once you've made the changes you wanted to, you'll want to install your version to be sure that your new feature is working properly.

Just in case you would like to try out different versions, we recommend you use a virtual environment to test it.

Before you can install and try out your own version, you'll have to build your own package:

This will create a a distribution package under a folder called dist.

Installing your version in a virtual environment

Go to wherever you have your virtual environment, open a terminal and execute the following commands:

source bin/activate
export DRM4G_DIR = $PWD/conf 
pip install path/to/drm4g/package

DRM4G_DIR is where the configuration files will be installed. More information here.

And that's it. Now you can use and test your own version of DRM4G.

For other ways to install the DRM4G, you can check here.

How to debug code

You have at your disposal a number of ways to check what could have gone wrong when something breaks.

Via the DRM4G CLI

Via the logger

Via the job's logs

Our Git workflow

In this section you'll find the guidelines of how we tackle the development process.

As mentioned above, to us, our central repository will be a private one hosted by GitBucket, but in addition we have a second public one hosted in GitHub to make the DRM4G accessible to anyone that might want to contribute to the project.

To add the GitHub repository as a new remote:

git remote add github

Both this two repositories have at least two branches, the master and the develop branches, that must be synchronized at all times.

If during development, you find yourself working in a team and wish to share your code, push your work to our central repository in GitBucket, not GitHub.

git push -u origin <branch_name>

Something to remember then, is that when you've finished your work on the branch, you musn't forget to eliminate it from the remote repository.

git branch -d <branch_name> #deletes the branch from your local repository
git push origin :<branch_name> #deletes the same branch from the remote repository

Another reminder, is that before pushing your work onto the remote repositories, you should always check that no changes have been made in them.

git remote -v update #updates your remote refs and shows the state of the branches
git status -uno #informs you whether your current branch is ahead, behind or has diverged from the remote

In the case that changes exist in the remote repository, you should perform a pull, resolve any possible conflicts, and then make the push.

git pull origin <branch_name>
#do necessary operations
git push origin <branch_name>

Adding new features

Each time some big change or new feature is going to be implemented, a new feature branch has to be created from the develop branch.

The feature branches are how new functionalities are introduced and tested. Normally the finalization of one of them will also define when a new release will be published, but that's not always the case since a new release may include more than one new feature.

git checkout develop
git checkout -b drm4g-new-feature #it will switch you to the new branch

When finished, the branch has to be merged back into the develop branch. After it can be deleted.

git checkout develop
git merge --no-ff drm4g-new-feature
git branch -d drm4g-new-feature
git push origin develop
git push github develop

To make the log more readable, in the cases in which a lot of small commits were made in the feature branch, it may be advisable to rebase to merge some commits before doing the merge into develop:

git rebase -i <hash_code>

Getting ready for a release

Once all the new changes for the next release have been added to the develop branch and it is at a stable point, it's time to publish a new release.

From this point on, all the following changes done on the develop branch will be for the following release. So, to avoid halting the development of the project a new release branch is created indicating the new release number.

It is in this branch where the version number of all the files will be modified, and where the code will be brought to a release ready state. That means that it is where minor bug fixes will be made, where comments and unnecessary code snippets will be removed and other maintenance tasks will be carried out.

When ready, all that needs to be done is merge it into the master, create a tag, update the remote repositories and publish the new release.

git checkout master
git merge --squash drm4g-X.X.X
git commit -v
git tag X.X.X
git push origin master
git push origin --tags
git push github master
git push github --tags

Updating the develop will be a bit different. If it is ever needed to rollback to a previous version, its commit has to be accessible. So merges to the develop branch won't be squashed.

git checkout develop
git merge --no-ff drm4g-X.X.X
git tag X.X.X
git push origin develop
git push origin --tags
git push github develop
git push github --tags

Aferwards you can just delete the release branch.

git branch -d drm4g-X.X.X


As an exception to the normal flow of the development, in the cases when an important error is discovered only after the release has been published, a hotfix branch can be created from the master to fix it.

After the problem was solved, you'd have to follow the instructions to prepare for a new release, except considering the hotfix branch to be the release branch.

If it turns out to be a critical error and not something fixable in a few hours, the release would have to be retracted until the issue got resolved.

Publishing a release

After having updated the master, it's time to publish the release.

  1. First, the package has to be uploaded to PyPI, there's a few ways to do this, but you'll need to have an account with access to the groups ?PyPI page.
  2. Run the command python register or modify your ?$HOME/.pypirc file and add your credentials to be able to submit package data to PyPI.
  3. Finally submit the distribution files.

At the end, the last step is to update the realese wiki page and the references in the section "New releases" of the DRM4G's main wiki page.