Repository navigation
Request: Can you please move /doc/spec into its own repo? #1568
Description
In #1562, @MichaelMure added a formal spec at the request of @mellowagain. I personally consider this to be a fantastic move on the part of the project as it would allow systems that store information about issues to interchange that information as and when needed. However, I'd appreciate it if the spec was moved to its own separate repository. My reasoning is that since it is a specification that could be shared between projects and languages, it is important enough that it should be it's own 'thing'. Why?
- The spec should be front and center, not buried. That makes it easy to point other projects towards it.
- The spec should have associated test data and test procedures. As more projects adopt the spec, they'll contribute more test data and procedures to it. These will be language and platform independent, allowing all projects to share their collective wisdom with one another.
- As the spec is refined, it may eventually meet the requirements to become an official IETF standard of some kind. This refinement will likely be separate from any single implementation, including
git-bug's implementation. - The licensing requirements of a spec may be different from the requirements of a given project (I am not a lawyer, so I don't know). E.g., while
git-bugis licensed under GPL v3.0, other projects may have different licenses, and it's unclear if implementing the spec while it's part of thegit-bugproject requires all implementations of the spec to adopt a GPL v3.0 compatible license. This could make it problematic when implementing the spec (again, I'm not a lawyer so I don't know. I've just had to deal with enough legal issues in my life that I'm paranoid about them). - Finally, I think it'll save the collective sanity of all of the
git-bugdevelopers; by keeping the spec as a separate repo, issue reports in thegit-bugrepo will really refer togit-bug's code, and not the spec.
Anyways, thank you again for making a spec. It's definitely a big help to the global community!
Activity
MichaelMure commentedon Jun 8, 2026
Make sense to me. What license would you suggest for the specs?
cfkaran2 commentedon Jun 8, 2026
For the text of the specification itself, you could use either CC BY-SA 4.0 or CC BY-NC-SA 4.0. The 'SA' part should make 'Embrace, Extend, Extinguish' more difficult for bad actors. Note that I'm not a lawyer, so I can't guarantee that is true; so far, none of the licenses I've seen are designed to prevent that 1.
I'd also suggest following the IETF Internet-Draft Author Resources guidelines for the spec; this is less to get into the IETF (although that's helpful) and more because they have a lot of experience dealing with writing specifications. No need to reinvent the wheel, right?
Footnotes
Ensuring that a spec isn't polluted or otherwise held hostage by bad actors is a difficult problem. The Joint Electron Device Engineering Council (JEDEC) closed some loopholes via chapter 8 and Annex A of JEDEC's Manual of Organization and Procedure, which was put into place after the Rambus lawsuits. And I believe that various entities that own intellectual property related to QR codes offer free licenses so long as implementers follow the standard, which helps keep people in line. But so far as I know, there is no way to perfectly defend against all possible bad actors. In the end, my suggestions are really intended to raise the cost/benefit ratio high enough that it isn't worth it for any potential bad actors. ↩
cfkaran2 commentedon Jun 14, 2026
@MichaelMure Do you want me to take a crack at rewriting the spec to meet the IETF standards? If you create a new, empty repo in the git-bug organization, I can fork it and start making pull requests against it. That way you'll maintain control of the spec and can review any changes I make for accuracy.
MichaelMure commentedon Jun 14, 2026
Done: https://github.com/git-bug/spec
For the license, I'm considering https://github.com/CommunitySpecification/Community_Specification that I've seen used in another project, but it's a bit heavy for a sunday evening. I'll do that another time.
Otherwise, feel free to PR some improvements, but aiming for IETF is likely way more that needs to be. I would focus on solving current problems: readability, correctness, ...
cfkaran2 commentedon Jun 14, 2026
@MichaelMure Thank you! I'll create issues in the new repo.