Git tips and tricks

[jlaurens]

Here are 2 articles concerning the Fork-and-Branch workflow where they explain how git can be used in practice. Below are some of their ideas that I find useful, most of them are listed for the record with a personal POV. The main point would be the "Create base develop branch" section.

• using-fork-branch-git-workflow
• our-git-workflow-forks-with-feature-branches

In particular, the latter's Whole workflow example in a nutshell (at the page bottom) seems helpful. Here is copy annotated with ideas from the former article.

Fork-and-Branch workflow

Some of next CLI commands may be integrate to GitHub, your favorite IDE, GitHub desktop, VScode.

Initialize new repository

done: this is latex3/l3build repository

Create base develop branch

Missing
I vote for two development branches:

• dev for short term changes
• future for long term changes

Fork repository

• Goto latex3/l3build repository
• Click the top right fork button, and follow the instructions

Next instructions concern the fork

Clone your fork locally:

$ git clone https://github.com/[user-name]/l3build

Or from your fork https://github.com/[user-name]/l3build click the green download code button, it should open GitHub desktop when available.

Add upstream remote:

$ git remote add upstream https://github.com/latex3/l3build

With GitHub desktop, this may help at least OSX users

Create feature branch diverged from develop branch:

$ git checkout -b [branch-name] dev

or

$ git checkout -b [branch-name] future

[branch-name] could be feature-something when related to a well defined feature.

Get your work done and commit it to your repository:

$ git add [files-to-add] or git add -A
$ git commit -m "Commit message"
$ git push origin [branch-name] -u

Integrated in some IDEs.

Create pull request to main repository

In the forked repository or with your local IDE capabilities.

This SO question explains how to target a pull request to a specific branch:

• either change the default branch of the fork (before the pull request is created)
• or edit an existing pull request and change its base

If the pull request would contain to many commits, a git rebase can “squash the commit history”.
More details in this article.

If the pull request aims at solving an issue, the issue number should appear in the pull request.

Ask someone or wait for code review

This happens in the main repository. It may need some time

Fix your issues or conflicts if there are any

Change the forked code and commit changes, they will update the pull request accordingly

Get your code merged to the main repository

If nothing went wrong!

When it is time, merge develop branch to release branch by creating a pull request or merging it manually:

In the main repository

$ git fetch upstream
$ git checkout -b release-v0.1 upstream/dev
$ git push upstream release-v0.1

Enter the fix state

• Test your branch, fix it if necessary by creating fix branches diverged from release:

$ git fetch upstream
$ git checkout -b [fix-branch-name] upstream/release-v0.1

• Make pull requests with fixes, get them passed through code review and merged
• After everything is done, merge release branch to master (or create pull request) and tag it as a next successful milestone in your project:

$ git checkout master
$ git fetch upstream
$ git merge [release-branch]
$ git tag -a release-v0.1
$ git push upstream master

• Repeat whole process

[josephwright]

Create base develop branch

Missing
I vote for two development branches:

* `dev` for short term changes

* `future` for long term changes

There are various approaches to using branches in Git. For us, the fact that one release stream = one CTAN package means that we've tended to stick to just a single (master) branch. That's not the case for say https://github.com/latex3/latex2e/ as we have on CTAN a -dev version. Here (l3build) I'm not sure we need that: other than the check target, we can afford a bit of 'variability' in outcome. (Even for check, over time we have had to make breaking changes to get the normalisation ... better.)

[jlaurens]

What about the 'experimental' branch?

[josephwright]

What about the 'experimental' branch?

That's @cereda's experiments - nothing wrong with having multiple branches, all I meant is we haven't needed a 'permanent' two-branch approach to-date.

[cereda]

Hello! 😉

I would favour the following scheme:

• master: the master branch, holds l3build-current, the official released version. Nothing is directly committed to this branch.
• development: this branch holds l3build-next, and every commit related to the next version will be in this branch. When a release is agreed, we merged it into master (and tag it accordingly), and keep committing stuff to this branch.

We do this approach at IoT and I must say it works wonders. I personally do not mind having other branches (that's why they exist, for experimenting things). The only thing I would be boring and demanding is regarding work flows: new branches can be merged into development, but never to master. 😉

Also, at IoT we use the format proposed at Keep a changelog for, well, our changelogs. See, for instance, this example for albatross in the development branch: we keep track of things we do in the [Unreleased] section of it; it helps a lot, as we know what has been done so far and what we have to document later on.

[josephwright]

Sounds like the approach we have in the main LaTeX repo and not dissimilar to GitFlow. (For LaTeX2e we are a bit more flexible on commits to master.)

[FrankMittelbach]

putting branching hotfixes of the released version from master (and then later porting them back to develop if released) is the approach we take for 2e and it works well and see not good reason to alter that practice (or introduce a quite different one in other latex3 repos.

[FrankMittelbach]

having said that, most of the latex3 ones are simpler with just master and the occasional extra branch (as they don't see much development or development from several people) but on the whole I also prefer the master/develop model.

[zauguin]

Clone your fork locally:

$ git clone https://github.com/[user-name]/l3build

Or from your fork https://github.com/[user-name]/l3build click the green download code button, it should open GitHub desktop when available.

Add upstream remote:

$ git remote add upstream https://github.com/latex3/l3build

With GitHub desktop, this may help at least OSX users

IMO that's a recipe for unnecessary complications. If you don't know much about get it will probably end up with the user having the development branches tracking the fork and not upstream, therefore pulling in them does not do the expected thing by default. In my experience this leads to people proposing PRs based on relatively old branch states since they never pulled from upstream. It works much better if the repo starts out as a clone of upstream, all branch tracking is setup from there and then the fork is added. (You can always set the pushDefault to your fork if you want to to keep it up to date, but that can be left for the more advanced users)

[jlaurens]

I must confess that it is a bit opaque to me.
What is exactly the replacement you suggest, what are exactly the replacement commands/actions to perform?

[zauguin]

Create pull request to main repository

In the forked repository or with your local IDE capabilities.

This SO question explains how to target a pull request to a specific branch:

* either change the default branch of the fork (before the pull request is created)

* or edit an existing pull request and change its base

Both approaches seem much more complicated than necessary. While creating a PR, you can just select which branch you want to target.

If the pull request would contain to many commits, a git rebase can “squash the commit history”.
More details in this article.

IMO we shouldn't recommend to squash commits before creating a PR. Of course a nicely rewritten commit history can make a PR more readable, but if we advice new git users to squash their history it just means that it gets harder to separate changes later.

If the history really needs some cleaning up, we can always do that by ourselves while merging.

If the pull request aims at solving an issue, the issue number should appear in the pull request.

I would go a step further and say that if the PR really aims to solve an issue, it should reference it with "Solved" or another one of the magic keywords.

[jlaurens]

Too many commits could mean in that case:
"in progress"
"almost there"
"Done"
"in fact not done"
"Now it's done"
Cleaning up that kind of commits is time consuming and maintainers may have something more important to do.

I personnally use many "in progress" commits because I happen to work on different machines.