Suggest the usage of conventional commits as a standard

[RobPasMue]

It is a typical use case to follow the Conventional commits standard for commiting

https://www.conventionalcommits.org/en/v1.0.0/

I'd suggest adding it as a best practice. Conventional commits allow users and maintainers identify what is the purpose of both commits and PRs. There are tools that allow enforcing it on repos (using pre-commit hooks for example) which also reduces the burden on the maintainer to review that users are following the guidelines

[RobPasMue]

This issue might live better in a different repo? Just unsure which is the best location

[kierisi]

@all-contributors please add @RobPasMue for code, review

[allcontributors]

@kierisi

I've put up a pull request to add @RobPasMue! 🎉

[RobPasMue]

Thanks @kierisi!

[willingc]

Hmm... @RobPasMue I think it is reasonable to suggest for adoption when there are more than a handful of contributors to a project. Even for a smaller project, it is useful if it is lightweight (i.e. only requiring the title format). If you want to try it out on pyOpenSci/pyosmeta repo, I think that would be great.

[RobPasMue]

Sure! I can give it a try there! :) thanks @willingc - I will try to work on this in the next week(s)

[Midnighter]

I'm using this format for all of my commit messages (unless I get very tired or frustrated and know that I will squash commits anyway). So big 👍🏼 from me.

[lwasser]

y'all - @RobPasMue mentioned this to me at the pyOpenSci scipy sprint as well. I'm interested in doing this too. i see @tkoyama010 uses them. what i don't understand is how it works for content.

so i see there is feat for conventional comments. for a package that is clear how to use it. But what is i'm adding a new tutorial.

do i use

add: new packaging tutorial on X
feat(tutorial): new packaging tutorial on X

or some other approach?
I really love that idea, especially for core staff to do it at pyOpenSci. And it could be optional to have a "way we do things" but it doesn't have to be strictly enforced. I just don't fully understand how to use it in a non-packaged development environment.

[willingc]

@lwasser Historically, conventional commits were used to add consistency to commit messages in large projects to aid in autogeneration of changelogs. By using conventional commits, a tool could parse the messages into groups of "related" commits.

Standards add cognitive load for contributors, esp. new contributors. By suggesting as a good practice, it calls attention that it's important to consider how we communicate a PR's change.

There are multiple ways that you could encode your example:

• feat: add packaging tutorial on X
• feat(tutorial): add packaging tutorial on X
• docs: add packaging tutorial on X
• docs(tutorial): add packaging tutorial on X
• docs(X): add packaging tutorial on X

Personally, I think encouraging conventional commits helps add consistency. However, I wouldn't run a lint on conventional commits that would fail a PR though it would be fine to report the result of the lint. Keeping the cognitive load low and the project friendly helps to encourage new contributors who will over time adjust to the general norm of the project 😄

[tkoyama010]

@all-contributors please add @RobPasMue for idea