How to contribute

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 described here.

So please fork this repository and create a local branch in which to do your work, and then create a pull requests to the DRM4G repository.

Creating your working copy

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:

Open a terminal on the directory in which you wish your local copy of the repository to be stored (it's recommended to use an empty folder) and run the following commands:

git clone <your_repository_url> #your fork repository URL in GitHub
cd DRM4G
git checkout devel              #change your local working copy to 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.

The default branch is devel, and this is done intentionally, since the main will only be updated when a new release is ready for publication. This means that all pull requests to the main branch are not allowed and they'll rejected by default. The naming convention will just be to create branches in lower case letters separated by underscores (_) that describe what you're trying to accomplish with the branch.

Commiting changes {#commiting}

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.

Creating 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 fork repository's GitHub 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.

Adding new features and Hotfixes

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. Normally the finalization 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.

As for the naming convention for these branches, they can be anything separated by underscores (_). However the name should try to be describe what is being implemented with it.

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.

To keep the log history of the branches created, the merges to the devel branch, will always be done with the no fast-forward option --no-ff.

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>

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 main to fix it.

• This is done like this as to not disrupt the teams working on the devel branch.
• The nomenclature followed would be hotfix-MAJOR.MINOR.PATCH
• The version number would only have to bump up by one the PATCH version.
• All of the files would have to have their version numbers modified.

After the hotfix has been implemented and tested, you'd have to follow the instructions to prepare for a new release, except considering the hotfix branch as the release branch.

That means that a new release branch shouldn't be created. But this branch would have to be merged back into the main and the devel 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.

Problems merging branches

When performing a merge, there may be some complications.

If you get a merge conflict when for example merging a release branch (drm4g-X.X.X) into main, which would make you lose the whole automatically generated squash commit message since you'd have to resolve conflicts and commit on your own, do this:

git checkout main
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

This will choose all of the changes made in the branch over the ones in the main branch, so only use this if you're completely sure of what you're doing.

Publishing a release

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 ishould be created indicating the new release number.

The nomenclature for all release branches will be a string followed by the new version in numbers in the form of drm4g-MAJOR.MINOR.PATCH and they will have their numbers increase following these guidelines:

• MAJOR version when you add some new functionality or you make incompatible API or CLI changes
• MINOR version when you improve some part of the DRM4G's functionality in a backwards-compatible manner
• PATCH version when you make backwards-compatible bug fixes.
• For creating tags, the same naming convention will be followed, albeit just the digits will be used.

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 main, create a tag, update the remote repository and publish the new release.

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

When performing the commit, the commit message will include all the previous commits made, but at the beginning a detailed message describing what is being added should be included. Squashing all the commits when doing the merge, will ensure that every commit in the master is a stable version and will make the log history cleaner, allowing us to easily see the changes made between commits.

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

After having updated the main branch, it's time to publish the release. In order to do so, first we have to create the wheel and dist pip packages and then upload them to pypi (you'll need to have an account with access to the groups ​PyPI page).

python setup.py sdist
twine upload dist/*

Managing the GitHub account

This section it's only for the administrators 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.

• If you agree with the changes made, and there are no conflicts, you can just click on the Merge pull request button. You'll automatically see a commit message that will look something like this: "Merge pull request #X from <contributor>/<branch_name>"
• Below that, you can write an "optional extended description".
• When running git log from the command line, you'll just see both lines shown as the commit message.
• When done just click on the Confirm merge button to finish.
• If don't agree or there are conflicts, you can click right next to the "Merge pull request" button, where it says command line instructions to perform a manual merge.
• Just follow the instructions shown there.
• Optionally, you could also try to solve the conflicts wiht the web editor, but this isn't recommended since you can't test what you're changing, unless the conflict is in a comment or a text message, not in the code.