Should we use a simpler rule for PR tags?

[yuanming-hu]

Currently, PR tags can be either fully lower-cased or start an upper-cased initial (e.g., [refactor] v.s. [Refactor]), depending on if the PR should be visible to end-users (contributor guideline). However, the rules are not followed in practice. I think there are two ways to go.

Stick to the old PR tag naming convention

Pros:

1. We can clearly classify PRs into two classes, developer-visible or user-visible, and the changelog is more friendly to end users.
2. ... (Inputs are welcome.)

Cons:

1. There is no way for maintainers to 100% ensure all PR titles follow the naming convention.
2. Judging whether a PR should be visible to the user may be an extra mental burden for contributors, especially newcomers, and there is no clear definition.

Simplify and use all lower case

Pros:**

1. Simplicity.
2. ...

Cons:

1. Changelog may get too long for users.
2. ...

Note that the current changelog (e.g., https://github.com/taichi-dev/taichi/releases/tag/v0.8.7) does not distinguish PRs types.

What do you guys think? Let's try to make a consensus by Dec 22, 2022.

(People who might be interested in this discussion: @strongoier @Vissidarte-Herman @ailzhang)

[writinwaters]

As you said, if we use lowercase tags once for all, then users will be overwhelmed by tides of PRs; if we stick to the old rule, then at least some PRs will be visible to the users. I do agree that maintainers are not perfect at differentiating PRs, but I think we can allow for a certain degree of error.

Questions from my end would be:

• Is there a reason why this rule was not followed? Is it simply because many developers were unaware of this rule?
• Did the internal developer follow this?

[yuanming-hu]

• Is there a reason why this rule was not followed? Is it simply because many developers were unaware of this rule?

It's just many developers were unaware, including committers. If we stick to the old rule, then we can ask the committers to make sure everyone follows the rule.

• Did the internal developer follow this?

Some do, and some don't :-) Again, if the decision is to follow the rule then the whole community should follow.

[writinwaters]

Is it possible for us to include this rule in our PR template? We already have one, which does not include this rule. We could put this rule at the beginning?

[strongoier]

In my opinion, we should think about what users would like to see in the release notes. If I am a user, I will not care about the PRs at all. Instead, I only care about user experience (new features, bug fixes, performance improvements, etc.). I prefer to see an introduction to all the improvements rather than dive into individual PRs and figure out what is relevant myself. Therefore, my suggestion is to let developers contribute a short introduction along with PRs related to user experience. And in a release note, we can collect these introductions as the main part. Regarding PR tags, I prefer to treat them as a simple classification to help other developers identify relevant PRs, so keeping them all in lowercase is enough.

[writinwaters]

You do have a point: The end-users do not care about individual PRs but features, which are composed of multiple PRs.

From my past experiences, maintainers will collect important PRs in release notes. The question is that, if we use all lowercase tags, who will collect these important PRs and how?

[ailzhang]

This is more like a tradeoff between work being done before a release and on a daily basis ;)

I agree with @strongoier 's suggestion about organizing our release notes from user perspective, which is mainly a step before we do a release. Currently this work is super lightweight as we just dump every PR title in the release note ;)

So to me whether to enforce/allow upper & lower cases in tags is more like a signal to the release oncall - whether they need to read a PR summary and include it in the release note.

So to the two extreme:

1. by default we use lowercase, release oncall need to look at every PR summary and come up with a nice user facing release note. (release oncall does it all)
2. we enforce contributors to write a section for one or few PRs and we somehow parse and include them in the release note. (distributed responsibility)

We're somewhere in the middle now that upper/lowercase in tags serve as hints but not enforced. I guess we can do 1 for now but it might not scale in the future when we have more commits. :P

[yuanming-hu]

Thanks for all the discussions here!

Therefore, my suggestion is to let developers contribute a short introduction along with PRs related to user experience.

Agreed.

And in a release note, we can collect these introductions as the main part. Regarding PR tags, I prefer to treat them as a simple classification to help other developers identify relevant PRs, so keeping them all in lowercase is enough. Therefore, my suggestion is to let developers contribute a short introduction along with PRs related to user experience. And in a release note, we can collect these introductions as the main part.

I feel like a good PR title itself can be "a short introduction" :-) Considering the maintenance cost of contributors and developers, and the user-friendliness of changelogs, I would suggest we stick to the old PR tag naming convention.

Nothing needs to be changed, except that

1. Committers are required to ensure the PR titles follow the rule;
2. In the changelog, we need to include everything that https://github.com/taichi-dev/taichi/blob/master/misc/make_changelog.py generates (instead of only the "full changelog" as what we do now).

Let's stick to this decision unless someone points out obvious caveats before Dec 22.