česky | english

Working with Git

This is a collection of bits of information and practical tricks which are useful during development work in the development workflow.

See also Software/DevelopmentWorkflow which has the same topic. Maybe some time we can merge this two pages?

Software/Assessment/Documentation is the current practice document.

Contents

Working with Git

Some background and Infrastructure

About repositories

CAcert is using several "official" repositories for development. For this reason you should consider to get comfortable with handling multiple "remote repositories" in your working copy, at least if you plan to be more deeply involved.

CAcert repository

This repository is located at git://git.cacert.org/cacert-devel.git. Everyone can read this repository, but only Software Assessors have commit access.

It is the "master" repository for the more important things, and CAcert's fallback for the case that Github will no longer provide its service, or the service is not considered appropriate anymore by CAcert.

Github repository

The Github repository at https://github.com/CAcertOrg/cacert-devel.git is the "everyday workhorse" for software development. Once we get to know you a little closer, and if you express some commitment to do software development for CAcert, your Github account will soon get commit access to this repository.

You can always fork this repository into your own account and propose changes by issuing pull requests.

Other projects

Git.cacert.org does host more projects beyond cacert-devel, see Software/DevelopmentWorkflow#Repositories for a more complete list.

These other repositories may or may not be mirrored in CAcert's Github account, just as it seems appropriate at the moment. The repositories on git.cacert.org should always considered the "master", if in doubt.

About branches

When working on CAcert software with git you should have at least a basic understanding of the function of some of the branches in the repository, otherwise it may be hard to get your change merged into the productive software.

release

Release tracks the state of the software as it should be installed on the critical system. Once a change is deployed on the critical system the tarball from the website is imported back in to make sure everything went well.

Changes to the release branch should only be done by Software Assessors.

This is the preferred basis for bugfix-branches.

integration

The integration branch is "almost" identical to the release branch, the only differences between the two branches should be the changes needed to make the testserver the testserver (for example color schemes, other certificates and such things).

In earlier times the "testserver-stable" branch had (probably) the same function, but since it was not documented, and probably got messed over time, it was decided to create a new basis.

Only Software Assessors should make changes to this branch.

Branches for bugfixes may be based on the integration branch, but usually the release branch is preferable.

bug-xxxx

These are the bugfix branches which contain code changes necessary to fix one issue tracked in the bugtracker https://bugs.cacert.org. The number of the branch is the same as the issue number on the bugtracker, so there's an easy way to link the two systems.

Normally these branches are based on the integration branch, but sometimes it may make sense to use release as the basis.

If you are a "freelancer" and want to provide a code proposal to fix a bug/issue from the Bugtracker, you make everyone's work easier if you put your proposal into a branch which follows these conventions.

The bug branches can be modified by all Software Developers. As an exception to the normal rule, for bug branches the Github repository should be considered the "master". They will be transferred to the CAcert repository if considered necessary, typically when testing is started or before the bugfix gets handed off to critical.

test-xxxx

The test-xxxx branches are temporary branches for test campaigns. They are based on the integration branch, and get one (or more) bug-branches, the set of issues that is currently tested.

By convention the number of such a branch is the same as the one of the (first) bug branch which is merged into is, but there is no real need to follow this scheme.

When a test branch is created, the file pages/index/feed.rss should be modified in addition to contain a note which makes it clear to which branch it belongs. This way testers can easily make sure that the testserver has the correct branch checked out by just having a look at the first page. A history of changes also makes sense, but is not considered essential.

Normally test branches are managed by Software Assessors, but in principle this is also acceptable if experienced Developers do this job.

Usually the testserver will have one of those test branches checked out. Those branches usually reside on the CAcert repository for the simple reason that this is the repository which the standard testserver can access most easily.

signer

This branch contains modifications that are required so the signer can run on the same system as the test server. It is normally not needed, and may currently (beginning of 2019) not be up to date.

It should only be meddled with by Software Assessors, and even they should use it with caution. Maybe this branch won't be necessary in the future as its own branch, since these changes may also be part of the integration branch.

testserver

This branch is obsolete, in earlier time this was used for the "status of the testserver". After its differences to the release branch got too big to be handled sensibly it was abandonned in favour of test campaign concept.

testserver-mods

Also an obsolete branch, nowadays the difference between release and integration branch should be exactly this.

For "freelance" developers

Freelancers in this context are developers which do not have write access to the Github respsitory of CAcert. This can be someone who just experienced a bug in the system and thinks that she can provide an easy fix for it.

Or it may be just the "newbie" developer proposing his first change.

It may even someone who wants to promote some library (or coding style or whatever) and can provide detailed code to make CAcert's software "better".

If you fall into one of these categories, the easiest way to provide your proposed changes is the following:

Create a Bugtracker issue. For this you must create an account on CAcert's bugtracker at https://bugs.cacert.org. This is probably the most important step, since no code change will be integrated without a corresponding bugtracker issue. No kidding!
Create a Github account, if you do not have one already
Fork the Github repository of CAcert into your Github account
Put your changes into a new branch according to the specification above
Send a pull request to CAcert

If this procedure is not acceptable for you ((maybe you hate Github?) please contact the Developer mailing list for possible alternatives.

Of course, if you prefer not to work for changes which noone else wants to have, it may also make sense to contact the mailing list in advance, and discuss your proposed changes there. Opinions about "better software" occasionally differ between different persons...

For software developers

How to do ...

These are short checklists on how to do specific things. Most times they are not the only way to do it, so if you think you have a better way try and share it!

Create a new branch for a bug/feature

You already have a local clone of the cacert-devel repository from git-dev and want to start a new branch.

Usually this is done by Software Asessors with commit access to the repository at git-dev, but it may also be useful when starting development on your local repository. Depending on your setup, replace "origin" with the alias of the repository you want to work on.

First of all get a working base. Not necessary if you don't make mistakes, but helpful otherwise...:

git checkout integration
git pull

Create the branch based on the server's integration branch:

git checkout -b bug-XXXX origin/integration

Now make your changes. If you're ready to commit do

git commit -a

Of course instead of using the -a switch you may also individually stage your changes, but then you most probably know what to do anyway.

Continue to improve your work and make further commits. Once you are ready to share your work and you have commit access to the repository do

git push origin bug-XXXX

For Software Assessors

How to ...

Install a bug on the testserver

On your local development machine do

git checkout integration
git pull
git checkout -b test-XXXX origin/integration
git merge bug-XXXX
Maybe repeat the last step if you want to add more bug branches to the test scenario
git push

Specifics for the CAcert testserver, may vary on your own testsystem:

Log in to the testserver test.cacert.org
Become root with "msu" (or sudo, whichever is available)
Change to /home/cacert/www/
git pull

Bundle and handoff to Critical Admins for Installation

This can only be done by Software Asessors.

git diff origin/integration...bug-XXXX > bug-XXXX.patch
If the bug was not merged into the integration branch origin/release may be more sensible as the base.
Send bug-XXXX.patch to Critical Admins with installation instructions
Add a note to the bug in the Bugs Database that the patch is handed off. If the patch file is small (your decision), add it to the note as a file attachment.
Change the status of the bug to "ready to deploy"? Currently this status is also used to tell Software Asessors that they should start creating the patch...
Merge the bug's branch into integration branch, and maybe also into the release branch. It's a similar procedure as with creating the test branch above, just skip the creation of the new branch (git checkout -b test-XXXX origin/integration) and replace "integration" by "release" if appropriate

Back to DevelopmentWorkflow