Releasing - VisionSystemsInc/voxel_globe GitHub Wiki

Sometimes (for contractual reasons) you need to have a private branch/fork of VoxelGlobe that you merge back and forth between master occasionally. While this can be done using many patterns, I will highlight the suggested pattern that will take care of how to handle this.

At VSI, we have a bitbucket account for private repos, and use github for public repos. This mixture causes a few headaches in terms of submodules, and multiple authentications. For your project, you can configure the entire projects anyway you want using your own .env file in conf.

#Different branches behavior

While there is only one master branch/main fork, all forks should keep the master branchs synced. Each projects can work publicly off of master, or privately off of their own branch. To make this all work sometimes there will need to be differences between the branches. These differences should be limited to one line in one files, conf/vip.env. This one file will specify which .env file to use that can contain as many differences as you want. The idea is each project branch has vip.env pointing to its .env file, and all of the .env files are merged into master, but vip.env only points to vsi.env. Since this is a non-standard thing in git, please follow these directions to keep the repo in a working state.

Branches

master - This is the main branch that should be identical between all forks. This practice give you a common anchor between all forkes
{my branch name} - This represents your project branch. After everything has been merged, it should only have one line in conf/vip.env different between master
{my branch name}_release - This is a released version of the {my branch name} branch. It can have many other differences that are never intended to be merged back in, such as changing titles, the main page, headers, etc...
{my branch name}_merge - Throw away branch for prepping {my branch name} to be merged back into master. It changes that one line back so that a merge does not break master and make it point to a different .env file.
{my branch name}_merged - Throw away branch for creating a PR. It should contain one commit to merge into master.

Syncing forks

Not covered

#Creating a new branch/fork

Suggested: git checkout master
Create a new .env file in ./conf. Look at the other .env files to get an idea
git checkout -b {my branch name}
./just choose-release and select your new .env file
git commit
git push origin {my branch name}

Now you have a new branch with the one difference

Merging changes back into master

When you are ready to merge changes back into master, you want to merge everything except that one line back into master. To do this:

git checkout {my branch name}
git checkout -b {my branch name}_merge
(Optional) ./just update-docker-base-images
./just build push
./just choose-release, and choose vsi.env from the list
./just public-release
git commit
git checkout master
(For a proper PR) git checkout -b {my branch name}_merged
git merge --squash {my branch name}_merge
git commit
(For a proper PR) git push origin {my branch name}_merged
(For a proper PR) Fill out a PR to merge {my branch name}_merged in master, and merge
(For a manual Merge) git push origin master

The squash merge is necessary to break the tracking on conf/vip.env. If this isn't done right, when you update your project branch, it will revert to the master state which would be bad.

Updating your project branch

git checkout {my branch name}
git merge master

Having more complicated changes

You may want more than one line of difference between branches. It would only increase the changes of making a mistake if those were in your {my branch name} branch. Instead, create a new release branch that has changes that would never go back to master. This will simplify the pattern

Creating initial release branch

git checkout {my branch name}
git checkout -b {my branch name}_release
Make, add, and commit any changes you want in your release only, such as modifying the main page/headers for your project name.
git push origin {my branch name}_release
Set up {my branch name}_release as your make branch on your fork.

Updating your release branch

git checkout {my branch name}_release
git pull origin {my branch name}

That's it. There shouldn't be any more interactions with the _release branch and the other branches. If there are, you aren't following this pattern