<div dir="ltr">Would this also be a good time to include an official git commit template file to add inline documentation for evergreen commit messages?<div><br></div><div>Example: <a href="https://gist.github.com/lisawolderiksen/a7b99d94c92c6671181611be1641c733">https://gist.github.com/lisawolderiksen/a7b99d94c92c6671181611be1641c733</a></div><div><br></div><div>And include setting up the commit.template in the Evergreen Git wiki page as part of the quick start.</div><div><a href="https://wiki.evergreen-ils.org/doku.php?id=dev:git">https://wiki.evergreen-ils.org/doku.php?id=dev:git</a><br></div><div><br></div><div>This would help me follow standard formatting, and would help with things like prompting for testing plans, having a standard way of referencing the lp ticket, and a prompt for setting the release-note: entry.</div><div><br></div><div>Josh</div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jan 3, 2024 at 3:02 PM Josh Stompro <<a href="mailto:stomproj@gsuite.larl.org">stomproj@gsuite.larl.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">Sounds like a good idea to me also.  +1<div><br></div><div>I like the time saving aspect of it both for the reviewer and the author.  </div><div><br></div><div>Would it be helpful to also include the bug category?  Or is that already there via some other method?</div><div><br></div><div>Something optional like:</div><div>release-note: (client) Logging out on a page with a pcrud call floods browser with errors.</div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jan 3, 2024 at 11:05 AM Blake Graham-Henderson via Evergreen-dev <<a href="mailto:evergreen-dev@list.evergreen-ils.org" target="_blank">evergreen-dev@list.evergreen-ils.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><u></u>

  
    
  
  <div>
    Galen,<br>
    <br>
    I think it's a fine idea. At the very least, it couldn't hurt. I'll
    start putting that line in my commit messages where appropriate.<br>
    <br>
    I appreciate the time and consideration on the issue.<br>
    <pre cols="72">-Blake-
Conducting Magic
Will consume any data format
MOBIUS

</pre>
    <div>On 1/3/2024 10:27 AM, Galen Charlton
      via Evergreen-dev wrote:<br>
    </div>
    <blockquote type="cite">
      
      <div dir="ltr">
        <div>Hi,</div>
        <div><br>
        </div>
        <div>Inspired by recent discussion about improving the ease of
          writing release notes - as well as some friction I'm already
          running into dealing with merge conflicts on
          miscellaneous.adoc when doing patch review - I'd like to
          propose a convention for adding brief release notes entry to
          the commit messages.</div>
        <div><br>
        </div>
        <div>Specifically, I propose adding a new "Release-note:" tag to
          the commit message that might look something like this:</div>
        <div><br>
        </div>
        <div>-- BEGIN COMMIT MESSAGE --</div>
        <div>LP#12356873: Quux the frobinator in the most techie fashion
          possible</div>
        <div><br>
        </div>
        <div>Commit message and test plan</div>
        <div><br>
        </div>
        <div>Release-note: Fix patrons occasionally getting overcharged
          by a penny when paying fines online<br>
        </div>
        <div><br>
        </div>
        <div>Signed-off-by: ...</div>
        <div>-- END COMMIT MESSAGE --<br>
        </div>
        <div><br>
        </div>
        <div>The idea is that when rolling a release, one stage of
          preparing the release notes would be running a script that
          looks at the commit messages on the release branch since the
          previous release in that series, grabs the bug number and the
          commit message, then generates a list in AsciiDoc format
          suitable for plopping into the Miscellaneous section of a set
          of release notes.<br>
        </div>
        <div><br>
        </div>
        <div>Such a script should probably be forgiving about how it
          parses the tag, including accepting the likes of
          "Release-noTeS:". When there's no tag in the commit message,
          falling back to the first line of the commit message after the
          bug number might be a not-too-terrible fallback.<br>
        </div>
        <div><br>
        </div>
        <div>Some reasons to consider doing it this way:</div>
        <div><br>
        </div>
        <div>- It avoids merge conflicts on miscellaenous.adoc during
          patch review and committing<br>
        </div>
        <div>- Patch authors would not have to fiddle with formatting
          the LP bug URL for misceallaneous.adoc<br>
        </div>
        <div>- It avoids some problems that might arise by an
          alternative convention to include the release note entry
          somewhere in LP, including LP's poor API and the fact that bug
          reports tend to be, well, statements of problems, whereas
          release notes usually should be statements of fixes or
          changes.</div>
        <div>- When a committer (or actually, anybody in the review
          chain for a given patch) needs to supply a release note that
          wasn't supplied by the patch author, a "git commit --amend" is
          quicker than fiddling with miceallaneous.adoc.</div>
        <div>- The existence of such a tag can help clarify the purpose
          of the patch for anybody reading the commit, as my example
          above implies<br>
        </div>
        <div><br>
        </div>
        <div>When to use this convention:</div>
        <div><br>
        </div>
        <div>- For bug fixes and very minor enhancements that can be
          adequately described in a single line</div>
        <div><br>
        </div>
        <div>When not to use to this convention:</div>
        <div><br>
        </div>
        <div>- For anything that cannot be described in a single line
          due to scope, complexity, or because the patch or series adds
          new permissions or library settings. In such cases, the
          existing RELEASE_NOTES_NEXT convention should be followed.<br>
        </div>
        <div><br>
        </div>
        <div>Thoughts? If there is general agreement that this is worth
          trying, I will put an example script together.<br>
        </div>
        <div><br>
        </div>
        <div>Regards,</div>
        <div><br>
        </div>
        <div>Galen<br>
        </div>
        <div><span class="gmail_signature_prefix">-- </span><br>
          <div dir="ltr" class="gmail_signature">
            <div dir="ltr">Galen Charlton<br>
              Implementation and IT Manager<br>
              Equinox Open Library Initiative<br>
              <a href="mailto:gmc@equinoxOLI.org" target="_blank">gmc@equinoxOLI.org</a><br>
              <a href="https://www.equinoxOLI.org" target="_blank">https://www.equinoxOLI.org</a> <br>
              phone: 877-OPEN-ILS (673-6457)<br>
              direct: 770-709-5581<br>
            </div>
          </div>
        </div>
      </div>
      <br>
      <fieldset></fieldset>
      <pre>_______________________________________________
Evergreen-dev mailing list
<a href="mailto:Evergreen-dev@list.evergreen-ils.org" target="_blank">Evergreen-dev@list.evergreen-ils.org</a>
<a href="http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev" target="_blank">http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev</a>
</pre>
    </blockquote>
    <br>
  </div>

_______________________________________________<br>
Evergreen-dev mailing list<br>
<a href="mailto:Evergreen-dev@list.evergreen-ils.org" target="_blank">Evergreen-dev@list.evergreen-ils.org</a><br>
<a href="http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev" rel="noreferrer" target="_blank">http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev</a><br>
</blockquote></div>
</blockquote></div>