Improve our ability to classify PRs/commits

[pedroerp]

To improve our ability to classify PRs while summarizing monthly updates (and in the future, release changelogs), we are proposing three additions to our open source development workflow:

1. Adopting conventional commits:

Following on @assignUser 's proposal a while ago (#3330), conventional commits would help us differentiate new features from bug fixes, refactoring, documentation improvements, and so. Specifically, the proposal is to, moving forward, use the following pattern of commit title prefixes:

• "FEAT: " for new features being added
• "FIX: " for bug fixes
• "BUILD: " for build or CI-related improvements
• "DOCS: " for enhancements to documentation (only)

Example: #11017 would have been titled:

FIX: Timestamp and interval arithmetic bug

2. Changelog and Breaking API Changes:

To further improve our ability to summarize changelogs (either monthly or when cutting future releases), we would like to ask authors to add a "Changelog: " section to the PR description, whenever new features are added. The Changelog would contain a sentence (one line or two) summarizing the feature added by the PR. This message would automatically get processed while generating changelogs.

Likewise, any PR containing changes to APIs (or their semantics) should also contain a "Breaking API Changes: " section in the PR description that explains the change. This will help us keep track and summarize breaking API changes for future releases.

3. Component classification:

To help us further classify the areas and components a PR modifies, we propose to add a series of github tags, such as:

• "vectors", "types", "expression-eval", "operators", "connectors", "storage-adapters", "memory-management", ...

and so on. Please help suggest the exact tags needed. Many of them may already exist, but we should be more diligent about using them.

--

As with any changes, it will take us some time to adapt. These changes would naturally be documented in our https://github.com/facebookincubator/velox/blob/main/CONTRIBUTING.md guide to alert new contributors, communicated to the community, and enforced by maintainers and code reviewers.

Please comment below if you are supportive of the changes or not (if not, please explain why).

[pedroerp]

Cc: @mbasmanova @oerling @xiaoxmeng @majetideepak @assignUser @Yuhta @kgpai @rui-mo

@bikramSingh91 @kagamiori @aditi-pandit @yingsu00 @JkSelf

Please help other folks who might have an opinion on this.

[majetideepak]

This is very helpful for project management. The Arrow RS https://github.com/apache/arrow-rs/ project has been following this.

[Yuhta]

For 1, I think it's ok to adopt it for a pure informational purpose; using it for versioning would quickly go out of control because people for sure will tag the things wrong, and a big FIX is often more significant (in terms of functionality/performance change and breaking compatibility) than a small FEAT, these tags should not be used as criteria to bump versions.

For 2, it's very hard to define breaking change now because we still don't have an API. The most explicit and safe way would be starting creating an api directory first and move the things that we should track compatibility there. Still for Meta internal usage the interface is much broader, so even a change is not changing API, it could break internal stuff, we need to be careful about it. Also behavioral/performance change should also be considered breaking sometimes; this is much harder to track than interface change. I don't have a good idea how to track these things yet.

For 3, it feels redundant because it can be quickly implied from the list of files changed. So I would say let's keep these for issues and not tagging PRs with these.

[pedroerp]

Agreed with @majetideepak above.

@Yuhta I think the main point here is that today it is quite painful to summarize changelogs, since one person need to manually inspect PR by PR to organize them, figure out which component they touch, what API changes should be highlighted (for future releases) and things like that.

If we do a better job at collecting this data during development, organizing and summarizing this information in the future will be a lot easier.

[Yuhta]

I agree it's good for changelog purpose.

For versioning I would say we need more explicit tags, like:

• API_CHANGE
• PERFORMANCE_CHANGE
• BEHAVIOR_CHANGE

instead of FEAT, FIX, etc, which would for sure result in very wrong/confusing versioning.

[kgpai]

We should also probably have tags for refactoring etc, which dont exactly fall into any of these other buckets.

[majetideepak]

@kgpai refactoring would be a CHORE tag. @pedroerp should we add this?
@Yuhta, @pedroerp I think we should have the tags FEAT, FIX in conjunction with optional PERFORMANCE_CHANGE, BEHAVIOR_CHANGE.
A new function implementation would be FEAT. A simple bug fix would be FIX. They would not belong to either of the tags Jimmy listed.

[kgpai]

Curious, why not just call it REFACTOR , chore sounds very negative .

[majetideepak]

Breaking Changes:

We can be explicit and say Breaking API Changes:

[pedroerp]

Modified the proposal above.

[kgpai]

On 3 - Certain fundamental changes may affect many areas, In this case adding which areas affected might become inaccurate and probably not very useful.

[pedroerp]

Yes, these should be best effort. If there is nothing that matches the tags, I suppose it is ok to skip them. Hopefully most PR would match at least one of these tags though.