VCS Thoughts

[Joel Sherrill]

Hi

The project is undergoing a process and infrastructure renovation.
Twenty years of software engineering has brought a lot of
improvements to project development flow and supporting tools.
We want to use these newer tools to the fullest extent possible.
We do not want redundant effort or information.

Many of the tools we have used were the best "in their day".
At this point, CVS is an archaic tool without many capabilities
and it forced developers to invent ways to capture information
that it couldn't handle.  The new tools can save work if you will let them.

As a general rule, we should not ask nor rely upon a human to
do anything a computer can do.

I don't claim to know the perfect solution but I am learning what
the wrong things are.

Random thoughts from here down

+ Git summary is needed

+ I want to write code and let the tools do as much work for
us all as possible. This is about capturing and conveying
information. Modern tools are better at this.

+ ChangeLog's serve two roles:
    - capture information not known in CVS/SVN
    - let users see changes in just a tarball.

The first point is covered by git and writing quality change
descriptions is needed independent of VCS. From an information
viewpoint, ChangeLog entries contain dates, committer,
files involved, PR, and a description. git handles the first 3
with no help. The PR and description have to be human either
way.

The second point is arguable. The ChangeLog entries are
just hints at what changed. Without access to the VCS, you
don't really know what changed. These could just as easily
be automatically generated and would be just as marginally
useful as the current ChangeLogs. As Pavel suggests, just be
higher level description with short descriptions and PRs
addressed.

Ultimately without access to the VCS, you don't really know
what details were changed. You just have a blob of source
and hints. At least with the automatically generated version,
you could include links to the diffs.

After a lot of thought, I agree with Pavel's email that has been
linked to multiple times. We can generate a detailed log for
tarballs if that is desirable. But it should be more than ChangeLog
format -- it should be more useful.

A summary of changes is more useful. Things like "updated BSP",
"Added BSP", etc are more useful than 100s of lines of ChangeLog
which boil down to the same information. For details, you have
to go to the VCS.

+ We need atomic change sets for an automatic regression tester
which is kicked off on every commit. If commits are broken into the
subsets dictated by the placement of ChangeLogs, then we break
those sets . I know of three pending changes that involve multiple
spots in the tree that should be committed as a single change set.
Committing those in pieces will result in broken builds. This is not
an atypical pattern.

This is NOT an unimportant point. Integration of an automated
regression tester into the RTEMS Project workflow would bring
benefits.

+ I think that a one line git summary with no meat after that
is generally too little. Summaries like "obsolete" and "Misc. fixes"
are useless. They were useless in a ChangeLog and they are
useless now.

+ We are not a GNU project. We have followed some GNU
practices and used many GNU tools. But we are under no
obligation to do so. We are free to use whatever tools,
processes, and practices best meet the needs of our developers
and users.

Twenty years ago, GNU was the only place to look for best
practices in the free software community. Now there are
other large free and open source software communities
from which we can look to got best practices.

+ From the little reading I have seen, you can replace $Id$
with something using git. But the "what" is a hard question.

I would propose:

+ renaming ChangeLogs.
+ generating "log of changes" with links to diffs based on
    git commit information. These could be generated as
    part of downloading a tarball or via a script. These would
    be more useful than GNU ChangeLogs since they have
    links to the diffs.  When to generate them is a question.
+ Define "change file" as suggested by Pavel.
+ Define standards for git log messages:
    - good summary (not available in cvs/svn)
    - good description (always manual)
    - PR associated (always manual)
    - author (git manages for us with Author tag if needed)
    - date (git manages)
    - signed-off-by (not available in cvs/svn)

-- 
Joel Sherrill, Ph.D.             Director of Research&   Development
joel.sherrill at OARcorp.com        On-Line Applications Research
Ask me about RTEMS: a free RTOS  Huntsville AL 35805
     Support Available             (256) 722-9985