To make it easier and more accessible for anyone to play around with the DRM4G, we have decided to host our source code on ?GitHub.
If you want to contribute to this repository please be aware that this project follows a certain gitflow.
So please fork this repository and create a local branch in which to do your work, and then create a pull requests to the main DRM4G repository.
For those of you who wish to help but don't know how, the first thing you need is a ?GitHub account.
In our project's page hit the "Fork" button at the top right corner:
This will create a copy of our repository in your account where you'll develop your own feature or implement a bugfix that you may believe is necessary. You'll be submitting changes to this one until you are certain everything works properly, at which point you can request to have your changes integrated into the DRM4G's repository.
To continue, you'll need to setup a local repository where you'll be changing the code and doing your testing. To do this you'll need your repository URL, that can be obtained adding .git to your project page or by clicking on the "Clone or download" button:
In Linux operating systems:
git init #to initialize an empty Git repository git remote add origin <your_repository_url> #to make your local repository point to your remote repository in GitHub git fetch git checkout devel #to create a local copy of the development branch
To be consistent with our gitflow, all you'll be able to do is create feature or bugfix branches, and you'll have to follow our naming conventions to do so.
With this, you will now have DRM4G's source code at your disposal.
This section needs to be updated
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.
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.
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
After you've tested that everything is in working order, it's time to update your GitHub fork.
git add .
git commit -m "Description of the changes you've made"
git push origin devel
From here you'll have to create a Pull request.
As time passes, chances are that the main DRM4G repository has had other contributors merge changes into it, so you should first update your local repository and check that there are no conflicts.
git checkout devel
git remote add github https://github.com/SantanderMetGroup/DRM4G.git #just do run this command the first time to add the main repository to the list of your remotes
git pull github devel
If there have been any changes, but there are no conflicts, you can just push your changes into your remote repository.
git push origin devel
In the case that there are conflicts, resolve them and commit the changes, after do the push to update your remote repository.
After, you just have to go to your repository's web page and click on the "New pull request" button.
A message will tell you if there are any conflicts that need to be solved or if an automatic merge is possible. Then you just have to click on the "Create pull request", give this merge a title (which will serve as the commit message if the pull request is accepted), a comment if you want (can be useful to explain in more detail why this should be integrated into the DRM4G), and click a second time on the "Create pull request" button.
Now you'll have to wait and see if the administrator of the project accepts the changes you're proposing.
Another option would be to create a new branch from the "devel" branch and then try to make a pull request from that.
git checkout devel git checkout -b new_branch #make some changes git add . git commit -m "Description of the changes you've made" git push origin new_branch
The next time you enter your repository's web page, you'll see a new button:
Click on "Compare & pull request" to perform a pull request on to the main repository. The same will happen as when clicking on "New pull request" when on a previously existing branch.
The aim of this section will be to explain the process we follow to contribute to the development of the DRM4G.
Internally we synchronize private work with GitBucket, which is what will be considered as the private repository of the Santander Meteorology Group.
We use something similar to a ?gitflow workflow. Our main repository is hosted in GitHub, found ?here.
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 https://github.com/SantanderMetGroup/DRM4G.git #to make your local repository point to the remote repository in GitHub git fetch git checkout master #to create a local repository of the master branch git checkout devel #to create a local repository of the devel 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.
In this section you'll find the guidelines of how we tackle the development process.
As mentioned above, our central repository will be a public one hosted by GitHub to make the DRM4G accessible to anyone that might want to contribute to the project, but in addition we have a second private one hosted in GitBucket.
To add the GitBucket repository as a new remote:
git remote add gitbucket https://meteo.unican.es/gitbucket/git/DRM4G/DRM4G.git
Both this repositories have at least two branches, the master and the devel branches.
If during development, you find yourself working in a team and wish to share your code, push your work to our central repository in GitHub.
git push -u origin <branch_name>
Something to remember then, is that when you've finished your work on the branch, you mustn'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>
Each time some big change or new feature is going to be implemented, a new feature branch has to be created from the devel 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 devel
git checkout -b new_feature #it will switch you to the new branch
When finished, the branch has to be merged back into the devel branch. After it can be deleted.
git checkout devel git merge --no-ff new_feature git branch -d new_feature git push origin devel
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 devel:
git rebase -i <hash_code>
Sometimes you'll want to incorporate the changes or improvements made in one branch into another one. To avoid making the log history too complicated when merging the feature branch back into the devel branch, the merges will be fast forwarded.
git checkout branch_a git merge branch_b
Once all the new changes for the next release have been added to the devel 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 devel 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 repository 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 --tags
Updating the devel 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 devel branch won't be squashed.
git checkout devel git merge --no-ff drm4g-X.X.X git push origin devel
Aferwards you can just delete the release branch.
git branch -d drm4g-X.X.X
When performing a merge, there may be some complications.
git checkout master git merge --squash drm4g-X.X.X #conflict occurred git merge --abort #or in case you commited without realizing it "git reset --hard HEAD~1" to go back to the previous commit #"git reset --hard HEAD" if the "--abort" commands gives you this message "fatal: There is no merge to abort (MERGE_HEAD missing)." git merge --squash -Xtheirs drm4g-X.X.X git commit -v
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.
After having updated the master, it's time to publish the release.
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.
For the administrator of the DRM4G's GitHub repository:
When you see that there's a new pull request, either because you saw it on the projects page or because you received a message in your mail informing you about it, you can click on the "Pull requests" button.
This section exists in case there's a need to convert any other project from Subversion to Git, including tags, the same way that has been done for the DRM4G and WRF4G. There may be better ways of doing it, but this is the only one that we've tested.
The program used is called ?svn2git. Follow the link to see how to install it.
Once installed, you can try to use the options they have listed in ?usage.
mkdir <local_repository_folder>
cd <local_repository_folder>
svn2git https://meteo.unican.es/svn/repos/WRF4G/ --username <user_name>
git checkout <project_branch>
rm -rf WRF* #if you need to clean up
#if they were empty you won't need to make a commit
#rename the project branch
git branch -m master old-master
git branch -m <project_branch> master
git remote add origin https://github.com/SantanderMetGroup/<project_name>.git git push -u origin master
git tag git tag -d <tag-names> git push origin --tags
git branch git branch -D <every_branch>