Help wanted: Issue and PR templates, replacement for ticket dependencies

[Matthias Koeppe]

As discussed previously, Issue and PR templates on GitHub can provide a replacement for the Trac ticket box. See ​https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository

https://github.com/sagemath/sage-gh-templates-sandbox is open for trying out possible designs for these templates. A first draft of one template:

​https://github.com/sagemath/sage-gh-templates-sandbox/issues/new/choose

Related: Help is needed with choosing a good replacement for our Trac ticket dependencies. As suggested in ​https://github.com/sagemath/publications/pull/142#issuecomment-1259001501 and ​https://groups.google.com/g/sage-devel/c/hX6ojxlNwOU/m/dup_Ywu1BQAJ, we should add to ​the transition guide how to model Trac's ticket dependencies in GitHub PRs. See ​https://github.com/orgs/community/discussions/4477 for solutions.

This is part of https://trac.sagemath.org/ticket/30363

[seb....@gmail.com]

I think there are two steps to be taken. The first step is to define a suitable template to collect all the important information in the header of issues and PRs that we are used to from the Trac ticket box.

In terms of dependencies between PRs, this will map what we are used to. The second step according to discussion 4477 will go beyond that. So this has a lower priority. But it will be nice to have!

As for the first step, I would suggest having templates that mimic the Trac ticket box for example:

$ cat .github/ISSUE_TEMPLATE/trac_ticket_like_issue.md
---
name: Issue according to Trac ticket
about: This template provides a similar structure to a Trac ticket
title: "[Short Description] "
labels: 'p:major'
milestone: 'sage-9.8'
assignees: ''

---

# Checklist for creating a Trac ticket-like issue

- [ ] I have read [README.md](https://github.com/sagemath/sage/blob/develop/README.md)
- [ ] I have read [the Troubleshooting section in the Installation Guide](https://doc.sagemath.org/html/en/installation/troubles.html)
- [ ] I have checked that this will not be a duplicate
- [ ] I have chosen a label from the <details><summary>Type list</summary><ul><li>t:bug</li><li>t:enhancement</li><li>t:task</li></ul></details>
- [ ] I have chosen a label from the <details><summary>Priority list</summary><ul><li>p:blocker</li><li>p:critical</li><li>p:major</li><li>p:minor</li><li>p:trivial</li></ul></details>
- [ ] I have chosen a label from the <details><summary>Component list</summary><ul><li>c:algebra</li><li>c:algebraic geometry</li><li>c:...</li></ul></details>

# Information that used to be in the Trac ticket box

||________________________________________________||________________________________________________|
|-|-|-|-|
|Authors||Reviewers||
|Keywords||Report upstream||
|Dependencies||Stopgaps||

# Description of the issue

This would also help with the change of habits. But it seems that this cannot be done only through appropriate templates. As far as I’ve seen, there’s no way to have radio buttons or select lists with GitHub markdown, even with plain HTML. Therefore, we would also need to implement corresponding GitHub actions (see also my comment on issue 8 in the trac-to-github repo). These would be needed to synchronize between corresponding Trac and GitHub features, too.

If there is interest to have such a template I can volunteer to produce a first draft (but maybe this will take a while since I have only short time-slots and I’m inexperienced with these GitHub tools).

​

[John H Palmieri]

I like the idea of mimicking the trac setup, but moving away from trac also lets us reconsider parts of the trac interface. I personally do not find the "Priority" label very helpful, other than whether it's a blocker or not. What do others think? We could just ask people to label "Blocker" if necessary, or I suppose have one template for a blocker, one template for everything else. (Probably better to use labels, since we see issues change from blocker to not and then back again, so having different templates would be cumbersome.)

A broader question is, which parts of the trac interface do we want to keep, and which parts can we dispense with? Also, where is the right place to have this discussion?

[Tobias Diez]

You can have advanced more advanced controls like checkboxes or dropdownboxes in issue forms, see https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#dropdown. Some of this is used in https://github.com/sagemath/sage-gh-templates-sandbox/pull/1.

[seb....@gmail.com]

Probably better to use labels, since we see issues change from blocker to not and then back again, so having different templates would be cumbersome.

I agree! In general the predefined structure of templates is not guaranteed to be preserved through the live of an issue / PR as we are used to with the Trac ticket box. Everyone with write access can destroy it. Surely this will demand a higher level of discipline among developers.

A broader question is, which parts of the trac interface do we want to keep, and which parts can we dispense with? Also, where is the right place to have this discussion?

I don’t know. Maybe a Trac ticket, since this must be clarified before we migrate?

​

[seb....@gmail.com]

There are two essential disadvantages of the issue form:

1. It is not available for PR.
2. The given structure is completely flattened after the issue has been created. In particular, the entries of the dropdown menus of the issue header are not visible (i.e. dropdown boxes are flattened to the selected entry) .

An advantage is that the issue is not created until all checkboxes are set. So this can be used to make things mandatory. This doesn't seem to be possible with the template.

[John H Palmieri]

I think it's okay to not make things mandatory. For labels, I propose a simple approach first: "Blocker" or not, "Bug" or not. (Currently, the "Task" type isn't used much, so the major distinction is between "Defect" and "Enhancement". Changing to "Bug" or not captures this.) I like the current "Component" setup, and I don't know how to replicate that well with user-generated labels: we're going to get typos and variations: "AG" or "AlgebraicGeometry" or "algebraic-geometry" or ... But it's worth trying.

[Marc Mezzarobba]

John H Palmieri wrote:
> I like the idea of mimicking the trac setup, but moving away from trac
> also lets us reconsider parts of the trac interface. I personally do
> not find the "Priority" label very helpful, other than whether it's a
> blocker or not. What do others think?

I agree about the Priority field. I also find the Type and Component
fields useless most of the time. (Regarding Component, many of the
possible values don't map well IMO to either actual code components or
developer interests, but a few do. In any case, I don't think it should
be mandatory.)

More generally, I see little benefit in trying to stay close to the
format of trac tickets. I would just start with a few labels for ticket
properties that are widely used now (bug, blocker, maybe a couple of
well-defined components...), allow people to create labels and projects
as they see fit, and let new conventions emerge.

--
Marc Mezzarobba

[seb....@gmail.com]

More generally, I see little benefit in trying to stay close to the format of trac tickets.

I didn’t think of having this as the default template. Just an optional template for former Trac users who are less familiar with GitHub (like me). But as I’ve now seen, templates and issue forms aren’t the right tools for an interface, and it’s probably harder to do than I expected. Perhaps it would be sufficient to have a reference to the migration documentation in all the templates we offer, at least for the initial period after the migration has taken place.

​