Proposal for a MacPorts'ish commit message template

[Lawrence Velázquez]

> On Nov 1, 2016, at 6:51 PM, Marko Käning <mk-macports at posteo.net> wrote:
> 
> I know that many of you weren't in favour of a commit message template,
> but I propose one anyway, which I derived from KDE’s neat one, as I find
> it on the console quite handy to know when 50 or 72 characters are
> reached in a line:

To be honest, this template adds so much comment noise that I can't
imagine ever using it.

> --- ~/.git-commit-template ---
> #  Please enter the commit message for your changes. Lines starting
> #  with '#' will be ignored, and an empty message aborts the commit.
> #
> #   -> The title MUST not be longer than 50 characters. 

I don't think we should dictate a hard limit on this. Sometimes it's
hard to say anything meaningful in 50 characters, especially since we
prepend port names to the subject line. Anything less than 60 chars is
generally good enough.

> #   -> You MUST wrap all further lines at 72 characters.
> #
> #  For more information on how to write commit messages see MacPorts'
> #  wiki at https://trac.macports.org/wiki/WorkingWithGit#commitmessages
> #
> # ==[ Subject: One meaningful line ONLY!  ]======|
> 
> # ==[ Blank: Follow the Subject with a blank line, do NOT remove ]=====|
> 
> # ==[ Details: Describe what changed and explain why it changed]=======|

This is all informative exactly once.

> # ==[ Fields: Uncomment and edit where applicable ]====================|
> 
> # --[ Links to issues on MacPorts' trac ]------------------------------|
> #ISSUE:      <full URL to trac ticket>
> #RESOLVES:   <full URL to trac ticket>
> #BLOCKED BY: <full URL to trac ticket>
> #
> ##EXAMPLE:
> # ISSUE: https://trac.macports.org/ticket/98765
> #
> ##NOTE: Don't use '#'-notation, since it's a Pull Request ID on GitHub!
> #
> # --[ Links to other pull requests at GitHub ]—------------------------|
> #PR:      <PR ID>
> #
> ##EXAMPLE:
> # PR:      #123

As Clemens already noted, these aren't the supported keywords.

> # --[ FUTURE FEATURE TO IGNORE/TRIGGER BUILDS ON SPECIFIC BUILDBOTS ]--|
> #BUILDBOT: < ignore | list_of_buildbots >
> #
> ##EXAMPLE:
> # BUILDBOT: ignore
> # BUILDBOT: ports-10.9_x86_64 ports-10.12_x86_64
> #
> ##NOTE: This isn't yet implemented at MacPorts' GitHub!
> #
> ##NOTE: See relevant issue: https://trac.macports.org/ticket/52769
> ---
> 
> 
> I have fantasised a little here what concerns the (perhaps upcoming)
> BUILDBOT feature.

I wouldn't hold my breath on this.

> The links section is also just serving as an example, but it might be a
> good idea to define some useful keywords there as well.
> 
> I also introduced a pull request section, which might be nice to have
> for proper documentation, who knows.

We have the wiki and guide for documentation. This template is not the
place for documentation.

> But perhaps all this is overkill?!

In case it's not obvious, I think this is serious overkill.

vq