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

133 views
Skip to first unread message

Matthias Koeppe

unread,
Oct 10, 2022, 2:42:28 PM10/10/22
to sage-devel
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:


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.


seb....@gmail.com

unread,
Oct 17, 2022, 1:50:45 PM10/17/22
to sage-devel

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

unread,
Oct 17, 2022, 2:59:37 PM10/17/22
to sage-devel
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

unread,
Oct 17, 2022, 3:07:12 PM10/17/22
to sage-devel

seb....@gmail.com

unread,
Oct 18, 2022, 2:26:20 AM10/18/22
to sage-devel

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

unread,
Oct 18, 2022, 2:40:27 AM10/18/22
to sage-devel
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

unread,
Oct 18, 2022, 3:47:59 PM10/18/22
to sage-devel
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

unread,
Oct 19, 2022, 4:35:55 AM10/19/22
to sage-...@googlegroups.com
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

unread,
Oct 20, 2022, 3:18:35 AM10/20/22
to sage-devel

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.

Reply all
Reply to author
Forward
0 new messages