WorkingWithGit

note: the following notes are from 2012. Please note that the default branch was changed to 'main' on 2021-01-15

Here are a few hints to get started with hacking on MapServer with git. These can be considered "better" practices, and although they might seem heavier at the first glance, they really help in the long run.

Never make your work-in-progress changes directly in the "main" or "branch-x-y" branches.

These branches should nearly always reflect the state of their equivalent on the central repository, i.e. you should be able to cleanly pull changes from the central repository into these branches.

here's an example session when working on a bugfix or new feature that will be applied to 'main':

git pull origin main  # make sure 'main' is uptodate
git checkout main
git checkout -b my-new-feature   # branch off of main

hack on some code, this can take some time. commit often.

When you're ready, prepare your my-feature-branch to be merged back into the up-to-date main. This step can be skipped if main has not been updated on the central repo, or if you are positive that your changes will not interfere with the changes that happened on the main repo.

git checkout main
git pull origin main  
git checkout my-new-feature
git merge main

At this point, you may have conflicts to resolve. If fixing the conflicts takes some time, repeat the previous step until the merge completes cleanly.

You are now ready to publish your changes to the main repo:

git checkout main
git merge my-new-feature
git push origin main

Note in this case that your local "main" branch has diverged from the repo "main" branch only the time it took to run the merge command (which ran without conflict if you respected the previous steps) and the time taken to push the changes.

###Working with release branches Following the workflow described here http://www.net-snmp.org/wiki/index.php/Git_Workflow, I've setup a script in our repository that changes the way fixes should be applied to stable branches. The aim is to simplify the task of applying a fix to multiple branches. So, in the case where a fix needs to be applied to more than just main, this is the workflow to use:

• make sure you have an uptodate clone, and that your main and stable branches don't have any uncommited or unpushed changes

• pick the oldest branch your fix applies to (or that you are willing to support), for the example let's say it is branch-5-4

• set your working copy to this branch:

git checkout branch-5-4

• create a temporary branch for your fix

git checkout -b bug1234

• code, test your fix, commit, restart,etc...

git add changed_file.c
git commit -m "fixing bug 1234, first step"

• once the fix is ready merge it into branch-5-4

git checkout branch-5-4
git merge bug1234

• you are now ready to apply this fix in the newer release branches. A script automates this process:

sh stablemerge.sh

• what the script does is iteratively merge 4-10 into 5-0, then 5-0 into 5-2, etc, up till 6-0 into main. This means your fix is propagated to all newer branches down into main.

• for more complex fixes and/or very old branches, the fix will likely not always apply cleanly from one branch to the next. You'll be returned back to your shell with a message indicating which file has a conflict and asked to manually edit it to resolve. Once you've fixed the conflict, commit your edited file, and rerun the stablemerge.sh script to continue propagating your updated fix to newer branches.

• push your changes back to the repo

git push origin branch-5-4
git push origin branch-5-6
git push origin branch-6-0
git push origin main

Please try to avoid copy-pasting a fix in multiple branches to accomplish the same task, as it will result in conflicts the next time someone runs the process.