summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Eggert <eggert@cs.ucla.edu>2020-06-29 17:41:57 -0700
committerPaul Eggert <eggert@cs.ucla.edu>2020-06-29 17:42:16 -0700
commit834b866d39860f34fffda92ff8087133fcb3d0e9 (patch)
tree7e616ccae0a856fa847f8f609ea97a81ee2998e6
parentdf361999a72ee5a05f58fd375f4c56b5cab5bf92 (diff)
downloadautoconf-834b866d39860f34fffda92ff8087133fcb3d0e9.tar.gz
make fetch
-rw-r--r--doc/standards.texi52
1 files changed, 26 insertions, 26 deletions
diff --git a/doc/standards.texi b/doc/standards.texi
index f07bf623..1826fd3f 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3677,28 +3677,28 @@ where can it be found?
@cindex version control system, for keeping change logs
Historically, change logs were maintained on specially formatted
files. Nowadays, projects commonly keep their source files under a
-@dfn{version control system} (@acronym{VCS}), such as Git,
-Subversion, or Mercurial. If the @acronym{VCS} repository is publicly
+@dfn{version control system} (VCS), such as Git,
+Subversion, or Mercurial. If the VCS repository is publicly
accessible, and changes are committed to it separately (one commit for
each logical changeset) and record the authors of each change, then
-the information recorded by the @acronym{VCS} can be used to produce
-the change logs out of @acronym{VCS} logs, and to answer the above
-questions by using the suitable @acronym{VCS} commands. (However, the
-@acronym{VCS} log messages still need to provide some supporting
+the information recorded by the VCS can be used to produce
+the change logs out of VCS logs, and to answer the above
+questions by using the suitable VCS commands. (However, the
+VCS log messages still need to provide some supporting
information, as described below.) Projects that maintain such
-@acronym{VCS} repositories can decide not to maintain separate change
-log files, and instead rely on the @acronym{VCS} to keep the change
+VCS repositories can decide not to maintain separate change
+log files, and instead rely on the VCS to keep the change
logs.
If you decide not to maintain separate change log files, you should
still consider providing them in the release tarballs, for the benefit
of users who'd like to review the change logs without accessing the
-project's @acronym{VCS} repository. Scripts exist that can produce
-@file{ChangeLog} files from the @acronym{VCS} logs; for example, the
+project's VCS repository. Scripts exist that can produce
+@file{ChangeLog} files from the VCS logs; for example, the
@file{gitlog-to-changelog} script, which is part of Gnulib, can do
that for Git repositories. In Emacs, the command @kbd{C-x v a}
(@code{vc-update-change-log}) does the job of incrementally updating a
-@file{ChangeLog} file from the @acronym{VCS} logs.
+@file{ChangeLog} file from the VCS logs.
If separate change log files @emph{are} maintained, they are normally
called @file{ChangeLog}, and each such file covers an entire
@@ -3731,8 +3731,8 @@ batch of changes that belong together, also known as a @dfn{changeset}.
@cindex header line, change log entry
It is a good idea to start the change log entry with a @dfn{header
line}: a single line that is a complete sentence which summarizes the
-changeset. If you keep the change log in a @acronym{VCS}, this
-should be a requirement, as @acronym{VCS} commands that show the
+changeset. If you keep the change log in a VCS, this
+should be a requirement, as VCS commands that show the
change log in abbreviated form, such as @kbd{git log --oneline}, treat
the header line specially. (In a @file{ChangeLog} file, the header
line follows a line that says who was the author of the change and
@@ -3772,7 +3772,7 @@ Following the free-text description of the change, it is a good idea
to give a list of names of the entities or definitions that you
changed, according to the files they are in, and what was changed in
each one. @xref{Style of Change Logs}. If a project uses a modern
-@acronym{VCS} to keep the change log information, as described in
+VCS to keep the change log information, as described in
@ref{Change Logs}, explicitly listing the files and functions that
were changed is not strictly necessary, and in some cases (like
identical mechanical changes in many places) even tedious. It is up
@@ -3784,9 +3784,9 @@ benefits of providing the list of changed entities with each change:
@itemize @bullet
@item
-Generation of useful @file{ChangeLog} files from @acronym{VCS} logs
+Generation of useful @file{ChangeLog} files from VCS logs
becomes more difficult if the change log entries don't list the
-modified functions/macros, because @acronym{VCS} commands cannot
+modified functions/macros, because VCS commands cannot
reliably reproduce their names from the commit information alone. For
example, when there is a change in the header part of a function
definition, the heading of the diff hunk as shown in the VCS log
@@ -3799,7 +3799,7 @@ difficulties, and make sure it supports the source languages used by
your project.
@item
-While modern @acronym{VCS} commands, such as Git's @kbd{git log -L}
+While modern VCS commands, such as Git's @kbd{git log -L}
and @kbd{git log -G}, provide powerful means for finding changes that
affected a certain function or macro or data structure (and thus might
make @file{ChangeLog} files unnecessary if you have the repository
@@ -3809,13 +3809,13 @@ Mentioning the modified functions/macros explicitly allows finding the
related changes simply and reliably.
@item
-Some @acronym{VCS} commands have difficulties or limitations when
+Some VCS commands have difficulties or limitations when
tracking changes across file moves or renames. Again, if the entities
are mentioned explicitly, those difficulties can be overcome.
@item
Users that review changes using the generated @file{ChangeLog} files
-may not have the repository and the @acronym{VCS} commands available
+may not have the repository and the VCS commands available
to them. Naming the modified entities alleviates that problem.
@end itemize
@@ -3832,7 +3832,7 @@ part of the @code{vcs-to-changelog} module. Note that these scripts
currently support fewer programming languages than the manual commands
provided by Emacs (@pxref{Style of Change Logs}). Therefore, the
above mentioned method of generating the @code{ChangeLog} file from
-the @acronym{VCS} commit history, for instance via the
+the VCS commit history, for instance via the
@code{gitlog-to-changelog} script, usually gives better
results---provided that the contributors stick to providing good
commit messages.
@@ -3847,7 +3847,7 @@ followed by descriptions of specific changes. (These examples are
drawn from Emacs.) Keep in mind that the line which shows the date of
the change and the author's name and email address is needed only in a
separate @file{ChangeLog} file, not when the change logs are kept in a
-@acronym{VCS}.
+VCS.
@example
2019-08-29 Noam Postavsky <npostavs@@gmail.com>
@@ -3933,19 +3933,19 @@ rather than this:
* sewing.c: Make it sew. Patch by jdoe@@gnu.org.
@end example
-When committing someone else's changes into a @acronym{VCS}, use the
-@acronym{VCS} features to specify the author. For example, with Git,
+When committing someone else's changes into a VCS, use the
+VCS features to specify the author. For example, with Git,
use @kbd{git commit --author=@var{author}}.
As for the date, that should be the date you applied the change.
-(With a @acronym{VCS}, use the appropriate command-line switches,
+(With a VCS, use the appropriate command-line switches,
e.g., @kbd{git commit --date=@var{date}}.)
-Modern @acronym{VCS} have commands to apply changes sent via email
+Modern VCS have commands to apply changes sent via email
(e.g., Git has @kbd{git am}); in that case the author of the changeset
and the date it was made will be automatically gleaned from the email
message and recorded in the repository. If the patches are prepared
-with suitable @acronym{VCS} commands, such as @kbd{git format-patch},
+with suitable VCS commands, such as @kbd{git format-patch},
the email message body will also have the original author of the
changeset, so resending or forwarding the message will not interfere
with attributing the changes to their author. Thus, we recommend that