[MacPorts] CommitMessages modified

[MacPorts]

Page "CommitMessages" was changed by larryv
Diff URL: <https://trac.macports.org/wiki/CommitMessages?action=diff&version=13>
Revision 13
Comment: rewording here and there
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: CommitMessages
=========================================================================
--- CommitMessages (version: 12)
+++ CommitMessages (version: 13)
@@ -6,14 +6,14 @@
 
 == Guidelines == #guidelines
 
-1. **Subject.** Summarize your changes in the first line of the commit message. For very straightforward commits, this one line could suffice as the entire message.
+1. **Subject.** Summarize your changes in the first line of the commit message. For very straightforward commits, this one line could be the entire message.
   - **Include the most important information.** Don't assume that readers can see the entire commit message; subjects often appear in isolation (e.g., GitHub history listings, `git log --oneline`, `git shortlog`).
   - **Be specific.** Avoid vague subjects like "Update to latest version" or "Fix the build". For example, if you are updating a port to a new upstream version, mention the version number.
   - **List any modified ports first**, followed by a colon (e.g., "autoconf, libtool:"). To save space, you can use glob notation (e.g., "[[span(py3*-numpy:, style=white-space: nowrap)]]", "[[span(clang-3.![6-9]:, style=white-space: nowrap)]]") or describe the ports' commonality (e.g., "boost dependents:").
   - **Try to use no more than 50–55 characters**, and treat 60 characters as a hard maximum. Feel free to shunt minor changes down to the message body. If you are having serious trouble meeting these limits, consider breaking up the commit into smaller pieces that are easier to describe.
 1. **Blank line.** Separate the subject from the body with a blank line; otherwise tools that parse Git history will get confused. Plus, it looks better.
 1. **Body.** Use the rest of the commit message to provide context for your changes.
-  - **Say what the commit itself cannot.** What was the previous behavior, and why was it wrong or suboptimal? How does your commit change that, and why did you choose this particular approach? Don't just translate the commit diff into English. (However, some context is understood and need not be pointed out explicitly. For example, we assume that updating a port is desirable. You do not have to describe the deficiencies of the old version and improvements of the new.)
+  - **Say what the commit itself cannot.** What was the previous behavior, and why was it incorrect or suboptimal? How does your commit change that, and why did you choose this particular approach? Don't just translate the commit diff into English. (However, some context is understood and need not be pointed out. For example, we assume that updating a port to a new upstream version is beneficial. You do not have to describe the deficiencies of the old version and benefits of the new one.)
   - **Use full Trac URLs.** TracLinks do not work on GitHub (obviously), so refer to Trac tickets by URL instead of number (e.g., "!https://trac.macports.org/ticket/12345" instead of "!#12345").
   - **Use autolinked references** to refer to GitHub resources. The website [https://help.github.com/articles/autolinked-references-and-urls automatically links] "#//n//" to pull requests and [[span(SHA-1, style=white-space: nowrap)]] hashes to commits.
   - **Wrap body text at 72 characters.** Git does not do this automatically, so hard-wrap the body to prevent text from overflowing standard-width terminal emulators. This also ensures that the output of `git format-patch` adheres to [http://www.openbsd.org/mail.html#Netiquette good email etiquette]. (You can't do much about very long URLs, unfortunately.)
@@ -53,7 +53,7 @@
 Unlike Subversion, which stores changeset logs as mutable [http://svnbook.red-bean.com/en/1.7/svn.advanced.props.html properties], Git commit messages are integral parts of [https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#Commit-Objects commit objects], which are immutable. Correcting a commit's message replaces the commit and all its descendants with new commits (because every commit contains the [[span(SHA-1, style=white-space: nowrap)]] hashes of its parents). This may or may not be a problem.
 
 - You can correct any commit you have not pushed to GitHub by [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-the-Last-Commit amending it] or doing an [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages interactive rebase]. It's good practice to review local commits before pushing them.
-- You cannot correct commits that you have already pushed because our important branches [https://help.github.com/articles/about-protected-branches do not permit force-pushing]. (Force-pushing would be required because your modified local history would diverge from the history on GitHub.) You can comment on the commit's GitHub page instead.
+- You cannot correct commits that you have already pushed. Comment on the commit's GitHub page instead. (Modifying your local history causes it to diverge from the public history. Publishing this alternate history would require force-pushing, which we [https://help.github.com/articles/about-protected-branches disallow] because it's [https://git-scm.com/book/en/v2/Git-Branching-Rebasing#The-Perils-of-Rebasing bad practice].)
 
 If you have a relatively recent Git, you can easily check whether a commit `deadb33f` is already in the history of a remote branch:
 {{{
@@ -64,7 +64,7 @@
 
 == Configuring text editors == #editors
 
-Git chooses a text editor for composing commit messages from [https://git-scm.com/docs/git-var#_variables the following sources], in this order:
+When Git requires a text editor, it chooses one from [https://git-scm.com/docs/git-var#_variables the following sources], in order:
 1. the `GIT_EDITOR` environment variable
 1. the `core.editor` Git configuration variable
 1. the `VISUAL` environment variable
-------8<------8<------8<------8<------8<------8<------8<------8<--------

--
Page URL: <https://trac.macports.org/wiki/CommitMessages>
MacPorts <https://www.macports.org/>
Ports system for macOS

This is an automated message. Someone added your email address to be
notified of changes on 'CommitMessages' page.
If it was not you, please report to admin at macports.org.