← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/changelogs.txt

  • Committer: Martin Pool
  • Date: 2005-05-16 02:19:13 UTC
  • Revision ID: mbp@sourcefrog.net-20050516021913-3a933f871079e3fe
- patch from ddaa to create api/ directory 
  before building API docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/changelogs.txt
 
1
**********
 
2
ChangeLogs
 
3
**********
 
4
 
 
5
Changelogs have an interesting relation to version control systems.
 
6
They are, for some projects, the primary way of examining history.
 
7
They provide a pattern and standard for writing commit history, which
 
8
may encourage people to enter more details (function names, etc) in a
 
9
systematic way than they otherwise might.  The ChangeLog is available
 
10
offline, in tarfiles, or even when the project has been switched into
 
11
a different VCS.
 
12
 
 
13
GNU ChangeLog format is only the most important, not the only such
 
14
file.  Debian uses a different format for packages.  At a higher
 
15
level, 
 
16
 
 
17
At the same time the information there is some redundancy: both the
 
18
ChangeLog and the VCS want to hold the description of what has been
 
19
done, including descriptive text, names of files changed, etc.
 
20
 
 
21
Some people say__ that ChangeLogs are mostly needed because of the
 
22
limitations of CVS (and originally RCS): if it was easy to read the VC
 
23
history when disconnected and at local speed, and if there are atomic
 
24
commits then they might be needed rather less.
 
25
 
 
26
__ http://gcc.gnu.org/ml/gcc/2004-06/msg00270.html
 
27
 
 
28
There should be hooks called to create the log message template and
 
29
before committing it.  These might, for example, populate it with
 
30
space for per-file comments, or check that it is in the right format.