Store issues as dedicated 'issues' branch of main project repo

[banj]

What would it take to implement this system within a branch of the core/main repo of a project? I love the method of storing issues as text files and I was wondering whether it's advantageous or desirable to store and manage issues etc. separately to the project code...

Thoughts?

[dspinellis]

See also #7. Using the project's branches allows issues to be live only on a specific branch. Your proposed method provides a single global store for the issues. Each method has advantages and disadvantages.

[r2evans]

@dspinellis, I wonder if this is a misinterpretation. I agree that issues should not be visible only in individual branches; the current work flows in github and gitlab (at least) supports issues that are specific only to a project as a whole, agnostic to any branches within it.

I suggest that this could easily parallel GitHub (project) Pages and GitLab Pages, where the metadata (i.e., "not code") is stored in a specific branch that does not contain the actual code or content of the main project.

For instance, consider this tree of branches and files:

repo
+- [master]
|  +- py/
|  |  +- mycode.py
|  |  +- helpersfuncs.py
|  +- README.md
+- [fix/43_overflow]
|  +- py/
|  |  +- mycode.py
|  |  +- helpersfuncs.py
|  |  +- morefuncs.py
|  +- README.md
+- [feature/57_2fa]
|  +- ...
+- [pages]
|  +- index.html
|  +- css/
|  |  +- main.css
|  +- js/
|     +- main.js
+- [issues]
   +- 5a/
   |  +- 5a67f1...
   +- f6/
      +- f667f1...

I suggest that it is not difficult for the script to work in a separate branch than what is currently visible; if no other way, then this could use a git worktree in a hidden directory at the head of the main project repo dir.

A path-forward (to not break backward-compatibility) would be a failure-mechanism: if the needed infrastructure is not found in the current branch and directory, then change the "working directory" to the repo/.issues_branch project worktree, in which all files should exist. I don't think it adds much complexity to the code or to the intent of the project.

(This is a very interesting project!)

[dspinellis]

I agree that typical workflows are designed so that issues apply to all branches. This can be easily accomplished by storing them in a separate repo.

I find the idea of using a branch to use data that is completely different from that of the other branches (as is done in GitHub pages and is proposed in this issue) to be at odds with Git's design. As a result, working with such data is cumbersome, inefficient, and counter-intuitive.

PS Thank you for your kind words.

[r2evans]

I agree in a sense with your dislike of separate branches, more-so for gh-pages than here. However, to me, the alternatives have their own disadvantages:

• separate repo: sure, it's completely separate, but there are times when seeing a combined log might be advantages, which can only be done with two calls to git log and some smart date-based merging.
• subdir of current project: there's something to be said for changing docs while changing the code, but I interpret that more for inline (API) documentation and not necessarily external web presence, so it is not perfectly aligned. (It's not perfectly mis-aligned, either.)

The "subdir of current" is obviously bad for issues, since that would produce different views of issues based on where you sit, as you stated earlier. The separate repo is always a safe backup, I think.

The "separate branch" (as suggested) is greatly facilitated with worktrees, though, and I think greatly mitigates the problems of being cumbersome, inefficient, and counter-intuitive (with which I do not disagree). (When I learned about and started using worktrees, it made a huge impact on my dev-cycle. If you haven't worked with them before, I strongly recommend giving them a try, docs at atlassian and of course git-scm.)

As an example, let's say the git-issue supports using a separate branch, gh-packages style. Then I could do

host@~/myrepo> git worktree add issues ./.issues
host@~/myrepo> find . -type f
./README.md
./.git/...
./.issues/issues/xx/xxxxxx...
./py/mycode.py
./py/helpersfuncs.py
./py/morefuncs.py

and then all of the content your script expects is under myrepo/.issues/. The beauty is that I can reference (and change) both branches simultaneously, independently.

Yet another option would be git submodules, which I think allow for "nesting" another repo entirely within the subdir of the current repo. That might be something more to your liking, though I still contend a separate branch in the same repo has its advantages. I don't use submodules, so I may have this completely wrong. But if I'm right and that sounds more agreeable to you, then I contend that the biggest effective difference between a submodule and a worktree is primarily built on preference, not technology.

(On reading further, one problem with submodules is that a change to the submodule does not change the remote itself, so it's like a local-only fork of the other repo. Not quite right for here.)

[dspinellis]

I was not aware of Git worktrees, hence my intense dislike for the complications and inefficiencies of maintaining issues in a separate branch. With a worktree the idea seems workable, doable, and aligned with Git's design. Thank you for pointing this out to me. Would you like to contribute the change via a pull request? This should include a paragraph in the documentation outlining the advantages and issues with each alternative approach.

[r2evans]

I'd be interested in working on both this issue and (perhaps separately) #27. I'll look into it.

[dy]

Btw github also uses /docs/ folder for serving gh-pages.

From (my) dev experience perspective having issues in the same repository has significant pros:

• no need to create/run two separate repositories for the same project
• issues are useless standalone, they belong to main project (same as docs, demos, research, design, assets etc.)
• that's more convenient to clone single repository and have issues at hand, instead of remembering complementary routine for issues
• centralized settings, members access
• known practice (docs/gh-pages in github)

As for possible contradiction to Git design, forgive my impertinence to quote W3C, that statement might be suitable:

In case of conflict, consider users over authors over implementors over specifiers over theoretical purity

[dspinellis]

I wrote my initial response two years ago. I've since become wiser and I also read about Git worktrees. I can now appreciate that a Git branch can also be a name for a completely separate set of files (rather than a genuine branch from the source code trunk) and that Git worktrees can be used to provide the required storage transparency and also to simplify the implementation and operation.

Many thanks to @r2evans and to @dy for enlightening me!

[r2evans]

(and I apologize for being completely unavailable since making that recommendation and offer, sorry @dspinellis )

[kaveman-]

Tried the recommendation and it seems to work. This is what I did:

# existing repo with lots of commits
$ git checkout --orphan issues
$ git rm -rf .
$ git issue init -e
$ git mv .issues/* .
$ git checkout main
$ git worktree add .issues issues
$ git issue github import ${ORG} ${PROJECT}
# issues added without clobbering the main branch log.

if this is alright I can send a diff to init that sets this up.

[dspinellis]

Thank you @kaveman- for reviving this! I think we would like this to be an option (even the default) in git init. If you send a PR, please also update the documentation.

[kaveman-]

Thank you @kaveman- for reviving this! I think we would like this to be an option (even the default) in git init. If you send a PR, please also update the documentation.

sorry about the silence. couldn't find time to work on it. however, my teammate @sk-sajid is working on this and should be posting a diff real soon.