Remove the dependency on Zenhub

[daira]

Proposal: allow dependencies to be expressed in the initial comment of a ticket, using the following syntax (case-insensitive).

Blocked-by: <list of [[org/]repo]#number>
Blocks: <list of [[org/]repo]#number>

Note that unlike Zenhub, this doesn't prevent creating cycles in the graph. What I suggest is to render a general directed graph rather than a DAG, but colour the arrows that are part of a cycle in red. This makes it clear that cycles are an error and makes them easy to spot in order to fix them manually.

To detect cycles in a directed graph, use any linear-time algorithm for finding strongly connected components, e.g. Tarjan's algorithm, Kosaraju's algorithm, or the Path-based strong components algorithm.

[daira]

This is essential to fully expose the DAG publically and remove one of ECC's information asymmetries.

[shielded-nate]

I'm keen on satisfying this ticket (as far as the title) and I want to hash out the implementation more. I propose the following variation to @daira's proposal above:

1. The relationships are specified in the main ticket description instead of a comment. (For this to work well, developers may need to be able to edit ticket descriptions for tickets filed by others.)
2. The format is tweaked to be nicely readable in github flavored markdown.

Format

The format is a relation header followed by a bulleted md list of ticket references.

This format is chosen for two reasons:

• It's easy to parse.
• It renders nicely for humans.

Relations headers must be an md bolded relation name with a colon on a line by itself, for example **Blocked-By:**\n

The relation Blocked-By should precede Blocks if both are present. (This regularity is to help humans navigate/edit.)

Each list item line must be - #<NNN>\n which is a single ticket reference. Github renders these with titles.

Markup and Rendering Examples

Note: the ticket references chosen are just for illustration and have no relation to this ticket.

**Blocked-By:**

- #42
- #13
- #1

**Blocks:**

- #2 
- #3

-would render as:

Blocked-By:

• Milestone Goal UX improvements #42
• Wallet Dag: Add MnemonicSwift repo, remove unused repos #13
• DAG: Enable views to optionally show issues from known adjacent repos #1

Blocks:

• DAG: Add "dark mode" #2
• DAG: Enable a view with rear-looking "horizons" #3

Outstanding Issues

Locating metadata in Ticket Description

Will this always work well? Can all developers edit the Description to modify links?

Over-determined Format

Is allowing both Blocked-By and Blocks worth it? An ideal tool would always ensure the two sides of the relation are always rendered consistently, but this isn't the ideal tool. So for example ticket A could have Blocked-By: B and ticket B could have no mention of A (incomplete but consistent), or Blocks: A (the only consistent option), or Blocked-By: A (a nonsensical cycle), or both Blocks: A and Blocked-By: A.

IMO, it may be worth only supporting the Blocked-By relation which removes all inconsistency except for cycles (which are mentioned in the original ticket description).

[shielded-nate]

I started hunting for pre-existing tools to do this. After all, isaacs/github#210 (comment) was filed in 2014. Here's a quick summary after 10m of poking around:

First, all of the tools I found are only about tracking the dependencies and modifying close/acceptance criteria to require blockers are closed first. None of them generate the nice DAG visualizations of this repo. Given that, here's a quick evaluation of those tools:

• Support issue dependencies isaacs/github#210 (comment) links to Actions marketplace: blocking-issues (with latest commit ~1 month ago: Levi-Lesches/blocking-issues@87d4122 ). 👍
• And via Support issue dependencies isaacs/github#210 (comment) :
  • dependent-issues action
    • "looks pretty nice, it's a different approach than @Levi-Lesches by looking into comments for certain keywords. Also supports dependencies between repos. I guess pick the one that suites your use case most."
    • My note: latest commit z0al/dependent-issues@75d554c > 1 year old. 👎
  • ZenHub - external tool 👎
  • CodeTree - external tool 👎
• Another route is https://github.com/orgs/community/discussions/4928 which mentions the sub-issue private beta - only trees not DAGs 👎

IMO, it's worth considering using the syntax of Actions marketplace: blocking-issues. That looks like it only supports one relation/syntax: Blocked by: #X, #Y, #Z. This would allow the two tools to be used together. The features of blocking-issues that this tool lacks are:

• Update dependents' tracking comments when dependencies are closed.
• Block PRs from acceptance if any blockers are open.

I guess it does not / cannot block issues from being closed if blockers remain open, which is awkward.

[Levi-Lesches]

Seems you accidentally pinged me from that quote, but I'm glad you did!

with latest commit ~1 month ago

I don't commit very often, but that's mostly because I think it has reached a "good enough" point where it works without issue on all my repos, and I usually just commit to follow up on complaints or suggestions.

IMO, it's worth considering using the syntax of Actions marketplace: blocking-issues. That looks like it only supports one relation/syntax: Blocked by: #X, #Y, #Z

Sure, if you want the regex, here it is:

const regex = /blocked by:? ([#\d, ]+)/ig;  // this is in JS

I guess it does not / cannot block issues from being closed if blockers remain open, which is awkward.

As far as I know, there is no way for a bot to prevent an issue from being closed. Also, even though there is a relatively new "wontfix" close reason, many people still use the standard close to represent wontfix/no response/can't reproduce/already fixed/etc, so blocking issues from closing isn't as important as blocking a PR from being merged when it depends on some other code or features being merged first.

Let me know if you have any questions, and feel free to take some code from my repo if that helps.