new package: Update example to subject: verb version

[ermo]

Description

With the monorepo, we use the worklog.py script and the GH UI, which shows the git summary for each commit at a glance.

Therefore, the git summaries in commits should be as informative as possible so people don't have to go chasing the individual commit logs for relevant version information when looking for specific updates or summarising the weekly development churn in the forum sync notes.

This PR changes the old (and no longer useful) "Initial inclusion" git summary part of the commit message to a more useful "packagename: Add at version" summary.

Note that we already require "packagename: Update to version" for the same reason. This PR also expands on this by adding a section with other useful git summary commit message examples related to common package update scenarios.

[EbonJaeger]

This is a good start. I think we can improve it further, though. :)

[davidjharder]

I don't have much to add here.

• I agree with the direction Evan wants to go.
• I would advise against the term shortlog, we don't use it anywhere. I know "title" and "description" are not the correct terms for what is actually all part of the commit message, but people will understand them more intuitively, and github uses those terms.
• We should not link to "tooling central documentation", a repository our users are not familiar with and we do not control. We could steal that guidance and put it on our Git practices page later

A more heretical bit of advice would be to fix exactly one line with this PR to address the precise issue that kicked this all off. I would be fine with that. Your call ermo. The longer this PR is open, the more changes will suggest themselves

[TraceyC77]

I agree with David's points.

[ermo]

@davidjharder , @TraceyC77 , @EbonJaeger

Thank you all for your (excellent!) suggestions.

I've essentially achieved what I wanted with this, which is to shine a light on how the workflow and examples we show new (and returning) packagers will help make the monorepo commit shortlogs more useful to packagers (including Solus Staff) overall.

I have my hands full with Serpent now coming properly online and simply can't afford to give this the copy-editing time it needs in order to be of high enough quality to meet your standards AND be easy to read.

Therefore, I am of the opinion that this really ought to be taken over by the comms/doc team, as you are clearly better at judging what users need here?

Feel free to close this and use it as a basis for a better worded PR?

EDIT: As a show of good faith, I'm giving this a final cycle where I address the review comments to the best of my ability. After that, I nominate @EbonJaeger to drive it over the finish line so it ends up in the best possible place for users and Solus as a project alike.

[EbonJaeger]

I think this is almost there! This structure is much better and easier for the reader to get the specific information they want.

[EbonJaeger]

I have no further changes for this PR. Thanks for making this section better!

Regarding @davidjharder 's point about linking to the tooling center docs, I think that's out of scope for this PR and can be addressed by someone later on; the link was already present before this was opened.