1

I'm planning to use GitLab to manage Git repositories (mainly Linux kernels from various hardware vendors).

Currently, I'm using Gitolite to manage users on Git server and MediaWiki to have what a call a "branch table"; in other words, a table where the single users report:

  • branch name (e.g. xboard-feat-i2c2)
  • branch maintainer
  • short branch description (e.g. "started from rev 2.0.0, feature branch to implement i2c2 driver on custom hostboard X")
  • branch status (WIP, testing, ready to merge, aborted)
  • branch longer informations (e.g. "to build this branch you have to change this and do that (in respect to the default instruction). We currently have a problem on this.." and so on). On this section I also usually write reference to the test bed/test suite used to test this specific software.

The main problem here is that the above table is created manually, and sometimes, users forget to add branches or rename them.

I'm wondering whether there's a place in GitLab (or a similar tool) to insert this piece of information.

I'm currently planning to force the user create a README (or a BRANCHREADME, to avoid conflicts) on the root of the repository as explained here with all the required information and I'm wondering whether there's a way to create a new page in GitLab project to show all the README informations for the various branches.

jub0bs
  • 60,866
  • 25
  • 183
  • 186
amonthedeamon
  • 306
  • 3
  • 9

2 Answers2

5

We've come a long way since "put what everyone is doing in a big file that they always forget to maintain". What you're doing seems redundant with an issue tracker and pull request system. GitLab has those, so let's use them.

  • Make an issue for each task.
    • Name the issue after the task, something human readable.
    • Put the task's description and any other information in the issue.
    • Assign the branch maintainer to the issue.
  • Make a branch for that task using the issue number. git branch issue/123
    • If you want to use a fancier naming scheme, put the name of the branch in the issue (I'd recommend against it, keep it simple).
  • Use the issue comment system for any discussion about the branch/task.
  • Use issue labels for any status or category information.
  • When it's ready to merge, make a pull request.
    • Follow the normal pull request process.
  • When it's merged...
    • Delete the branch.
    • Close the issue.

This takes advantage of the GitLab issue tracker's good integration with the code. Issues are searchable, they have attached conversations, they can be referenced in commits (and vice versa) and they're archived after they're closed. The branch naming scheme is simple and allows future developers to easily track an old branch back to its development history (the branch name remains in the merge commit after deletion, so make sure you always git merge --no-ff).

Schwern
  • 153,029
  • 25
  • 195
  • 336
  • 1
    And GitLab's built-in wiki can be used for more general documentation that doesn't belong to a particular issue like, say, documenting the procedure outlined above. – ChrisGPT was on strike Feb 04 '15 at 18:45
  • IIUC Gitlab can directly link an issue only to commits (usually with something like "fixes #152") but there's now way to link an issue to a branch. Naming the branch with the issue number is a good clue – amonthedeamon Feb 04 '15 at 22:20
  • @Schwern: after it has been merged you suggest to delete the branch. This is fine to me, apart the fact that is hard to find the branch again in future: you'll need to look into the merge commit description (which report the name of the merged branch). Now I'm used to delete the branch but also to put a tag on it (merged/branchname) to easily recover it in case of needs. WDYT? (ref. http://stackoverflow.com/questions/1307114/how-can-i-archive-git-branches) – amonthedeamon Feb 05 '15 at 14:01
  • @amonthedeamon I don't see any harm in tagging old branches, but IMO using a tag is redundant with the commit description, probably also the issue tracker, and an extra step people will forget. It's rare that I want to go and find an old branch, more that I want to know what issue and branch a particular change was part of. For that I'd use `git blame` and/or search the commit descriptions. The main concern for me is, once merged, *no more work is done on that branch*. It keeps branches and issues manageable, and assures that when tasks are done they are *done*. – Schwern Feb 05 '15 at 18:47
  • @amonthedeamon I want into some detail about why I wouldn't bother tagging old branches. http://stackoverflow.com/a/28352246/14660 – Schwern Feb 05 '15 at 19:19
  • @Schwern, I perfecly undestand what you mean. However, at the moment my developers work "in rush" when doing they developers branches, committing everything, even debug printf(), not yet working code and so on. This need to be stripped out before merging (git rebase -i) by creating what i call a feature branch (which is clean and ready to merge, possibly without conflics by rebasing on current master). What I need is something that points to the original-debugging-development branch, because sometimes is useful to reach that debugging code (the development branch in not merged anywhere). WDYT? – amonthedeamon Feb 09 '15 at 06:13
  • @amonthedeamon I think any development process that involves committing non-working code somebody else is supposed to make work sounds like a low-quality nightmare that encourages bad practices and will swamp you with technical debt. Do they write tests? Why are you doing that? – Schwern Feb 09 '15 at 06:37
  • @Schwern, is not only a matter of non-working code, another use-case is, e.g., non working or non-stable hardware/software that need fixes (not needed in production environment). I need to let the developers be free to commit whatever they want (lots of printk(), weird fixes for hardware/software instability etc), later the will rebase their commits (or I'll do that for them..) but is useless to trash the old code, it may be useful someday (e.g. if you need to work again with the old unstable hardware). [link](https://github.com/smoynes/git-freeze) or tagging the branch is what I'm doing now – amonthedeamon Feb 18 '15 at 09:52
  • @amonthedeamon Ok. I got the wrong impression you were merging it all into master. It's just test branches, got it. – Schwern Feb 18 '15 at 18:11
3

My solution to my own problems, after working daily for a couple of year with GitLab to manage many project is as follows:

  • create an issue for everything (bug, new feature ecc). Describe the problem/idea and not how you're solving it
  • when start working create a new MR (this can be done with the button into the issue itself). This generate both a working branch and the MR (as WIP)
  • explain what you're doing into the MR
  • once the work is done, remove the WIP from the title and, either:
  • merge the MR and delete the branch
  • or: close the MR and delete the branch if it's not useful.

Please note that, even if you close the MR and delete the branch, the commit will stay there (even if not "directly" accessible via git), so you're not loosing anything of your work.

You can also use the same workflow when "reworking" a branch: I don't want to miss the original implementation (because I can add bugs/issue during the rework) so: - create a new branch, with a suffix of revision (e.g. -v1, -v2 and so on) - create a new MR for this branch, writing down what your rework/review - comment the original MR or the new one (it doesn't really matters) with a reference to the other MR (so they are "linked") - close the original MR and delete its branch

This allows me to both have a low number of open branch per project (usually are merged or closed) but have documentation about the work done and never loose a single commit

amonthedeamon
  • 306
  • 3
  • 9