Best practices for referencing a git-bug issue in a commit?

[arcanemachine]

A great benefit of this project is the paper trail it provides: Commits can reference issues, and issues can reference commits.

When creating a new bug, the issue is given an ID. I had been placing this ID in my commits to easily reference the issue if needed.

However, I have noticed that each time I clone the repo and pull from a bridge, the issues are given a new set of hashes/IDs. This means that I cannot reference an issue using this method. (Of course, I may just be doing something wrong.)

Here is my question: Is there a best practice for referencing bugs by some sort of ID number, so that commits and issues can reference each other? (preferably one that is not tied to an issue tracker ID# on an existing bridge)

Follow-up question: If git-bug isn't currently generating a static hash for each issue, perhaps there is a way for it to do so? A git commit, for example, is the same each time the repo is pulled, thereby giving each commit a reliable reference ID#.

Is there a way to do this entirely within git-bug without relying on the implementation details of a specific bridge (e.g. GitHub issue IDs)? Relying on the bridge may be problematic (e.g. GitHub issues can be deleted, creating Issue # gaps that may pose a problem if the issue tracker is ported to another bridge... issue numbers would likely be desynchronized).

For now, I'll probably just generate a short random value to reference between both, but I'm curious what other people are doing (or if I'm doing something wrong :D).

Thanks

[MichaelMure]

I think there is two dimensions for this:

• how those reference are expressed and stored
• what those references point to

Let's start by clearing some things:

I have noticed that each time I clone the repo and pull from a bridge, the issues are given a new set of hashes/IDs.

This is "normal", for some definition of normal. As git-bug is a decentralized system, when you import bugs with a bridge, you can't know if some other machine somewhere in the world has done so already. It's just impossible. So that creates duplicate bugs in git-bug.

It's also impossible or ill-advised to generate the same hash, for multiple reasons. One sufficient reasons is that the original bug data will contain the date of creation, which in turn change the hash. That bug will also have an author (you) which will likely be different than on the other machine.

Now, how those reference are expressed and stored. What I suppose we could do is to have special markers in the stored text. git-bug would understand those and generate the appropriate link in each UI. Possibly, if this marker point to a git-bug object, it could be recorded as a dependency in the graph (similar as for files, see https://github.com/MichaelMure/git-bug/blob/master/doc/model.md#entities-are-stored-in-git-objects), so that it get pulled together.

As for what those references point to, that's where we can be clever. We can point to a git-bug ID of course, but not only. When a bridge import a bug, it adds metadata to the git-bug bug. For example the github bridge include the github ID and URL as metadata. Those won't change.

So we have any or multiple references for the same marker, and have the core+UI figure out what makes sense and how to display it.

[sudoforge]

Please keep in mind that some users may not be using bridges, instead using git-bug as their native and only issue tracker.

[LemmingAvalanche]

This issue overlaps with #18 but brings up different concerns.

---

My impression so far is that it is impossible to refer to a stable id for a bug.

I get the impression that the project is opposed to some prefix + incrementing numbers. I don’t care about being 100% distributed since I’m just using it for my own issues right now. And I am willing to risk using an issue prefix that someone else could have taken.

The final commit: stable and globally unique id

For the long term, it seems most important to link to the issue id in the immutable Git history (not whatever feature branch which might be rebased and so on). Conceptually (irrespective of what this program does) those issues should have a globally unique id at this point. They may or may not point to a central (not distributed) instance. Probably not archived since there might be more updates after the commit (maybe it fails to solve the issue).

Truly distributed issue tracking for this permanent part of the Git history (again as opposed to feature branches or mailing list patches) doesn’t seem worth the hassle.

The work in progress commits: SHA-1 or ad hoc prefixes with incrementing numbers

I use git bug for one project that I’m working on which doesn’t have an issue/bug tracker. There I note issues I find. I might try to solve the issues and send out patches to the mailing list. Then I finally go and close the issue if they get merged to/included in the main branch.

I have not tried to link commits and these bugs before. I just mention the branch name in the issue. But I might try this:

• Create a prefix for these bugs: my initials + the initial of the project (let’s say xyz)
• Issues are incremented manually: the fifth bug is xyz-5
• I can’t mention these issues in my commit messages because it is on my own (local/private) bug tracker
  • So I add a Git Note which says something like Fixes: xyz-5
  • These notes are not published
• But in case there are like three people who have my issue tracker and they might care: I can add a custom header with the issue key
  • X-Issue-Id: xyz-5
• Bonus: I can add this issue id as a suffix to my branch name (e.g. fix-negation-xyz-5 and use that to to discuss the branch outside of Git (like on the mailing list)
  • More likely that the branch name is unique among the currently active ones

This scheme permanently links bugs/issues but is still private to me. But the links can still be made available to others by publishing the Git Notes which tie the commits to the issue ids.

Issue key aliases

“The final commit” said that the issue key in the final commit should be the final, globally unique one. But using an id that people move away from is not necessarily a big deal. Issue trackers can change the “project” or whatever of an issue, thus changing the key, but still allow links to get routed to the right place.