zcash / developers

9 stars 11 forks source link

Remove the dependency on Zenhub #41

Open daira opened 1 year ago

daira commented 1 year ago

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 commented 9 months ago

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

shielded-nate commented 2 days ago

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:

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:

Blocks:

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).