proposed policy change: no ChangeLogs for regen files

proposed policy change: no ChangeLogs for regen files

[Frank Ch. Eigler]

Hi -

I find it very painful to make ChangeLog entries for every single
directory, when as a consequence of a localized configury tweak,
configure/Makefile.in/aclocal.m4/etc. files are regenerated all over.

The ChangeLog doesn't supply much useful information for regenerated
files.  Other than build-breaking situations, the history of regenerated
files is just not that interesting.  Consider them as an analogy
to the case of documentation files, for which the GNU coding standards
explicitly disclaim the ChangeLog requirement.

I propose that, for changes where local regeneration was incidental,
ChangeLog entries for the regenerated files no longer be added.

- FChE
-- 
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE7S396VZbdDOm/ZT0RAiJVAJ4xifkB5NkukbS6OcNVv9yyJDAeZACfbF2e
HTiuUzq+uOQFiTnWdZZbO/c=
=qoEP
-----END PGP SIGNATURE-----

Re: proposed policy change: no ChangeLogs for regen files

[Ben Elliston]

>>>>> "Frank" == Frank Ch Eigler <fche@redhat.com> writes:

  Frank> I propose that, for changes where local regeneration was incidental,
  Frank> ChangeLog entries for the regenerated files no longer be added.

Sounds reasonable to me.  One problem we're likely to have is making
newcomers aware of this policy decision.  Can you document it in a new
HACKING file?

Ben

Re: proposed policy change: no ChangeLogs for regen files

[Frank Ch. Eigler]

bje wrote:

: [...]  One problem we're likely to have is making newcomers aware of
: this policy decision.  Can you document it in a new HACKING file?

Thanks for the nag.  I've dusted off an old internal HACK-RULES file,
and plan to commit it to the public repository shortly:

------------------------------------------------------------------------

This file describes some of the required procedures for contributors working
on SID.  Please read and understand this before checking anything in.  Post
proposed diffs to this file on sid@sources.redhat.com, the project's public
mailing list.


* Special headers

Several files in sid/include/ define the SID low-level API, contained
in the sid:: C++ namespace.  By extension, this also defines the ABI
for compiled component modules.  Because of this, any functional change
to the headers causes instant incompatibility with far-reaching effects.
Therefore, the files that define the low-level API are special and change
extremely rarely.  The special header files are:

   sidcomp.h
   sidso.h
   sidtypes.h

You should NOT check in ANY functional changes to these files without
prior discussion on the project mailing list.  It would be most polite
to post proposed reasonably formatted diffs, and have convincing arguments
ready to justify them.  Sadist <fche> likes to try to veto anything
nonessential.

Whenever the low level API is changed in any way, the
API_MINOR_VERSION and/or API_MAJOR_VERSION values in sidcomp.h must be
changed.  This allows previously compiled component binaries to be
recognized as incompatible at load-attempt time.


* Utility headers

A growing number of header files define optional utility classes and
functions for SID component classes.  These definitions all go into
the sidutil:: C++ namespace.  They are used pervasively in existing
SID component code for convenience only.  These headers are never
installed via "make install".

Feel free to add reasonably formatted new classes/functions at will
into existing files, or new ones.  Convention suggests that any new
utility files be named sid*util.h.  Changes to existing classes may be
made, but only if all affected component sources continue to work.

The utility classes are used by components by a mere #include.  There
is no "sidutil" library for them to link in.  This means that these
headers define template classes/functions or non-template classes with
inline functions only.  One negative side-effect of this arrangement
is that of compiler memory bloat, so this may be changed sometime.


* Components

New components are absolutely welcome.  Here are a few steps that form
an informal checklist:

- Read up on SID architectural theory and practice.  Design
  it to be a nice self-contained portable component.  Avoid
  anti-component practices (custom APIs, global variables, etc.).
- Announce your intentions on the mailing list.  Good advice is
  available at no charge.
- Extend an existing component source directory, if your component is most
  conveniently derived from another.  Use a new source directory otherwise.
- Pick an appropriate component type string and shared library name.
- Record them in sid/component/CATALOG.  Name yourself as maintainer.
- Code it up.  Integrate it into the existing autoconf based build system.
- Avoid constructs that are not reliable in the context of a complex
  C++ program located in shared libraries / DLLs.
- Use a reasonable coding style.  However, in each component's directory,
  follow the style already present.  If there appears to be more than one,
  pick one, but don't introduce new ones.
- Document it using the standard XML DTD format in the source directory,
  to be installed into $pkgdata along with the generated .txt form.
- Build and automate some tests.  Choosing to not use dejagnu requires a
  good reason.

Improvements to existing components are welcome.  Please contact each's
maintainer for advice and perhaps approval.


* Mainlines

New mainlines (sid/main) or sid front-end scripts (sid/bsp) are absolutely
welcome, though are usually less necessary than new components.  Discuss
your intentions on the mailing list as you proceed.


* Check-in checklist

- Confirm that your code runs on both big- and little-endian hosts.
  We use mainly Solaris, Linux, Cygwin hosts.  Consider using several
  compilers.
- Add standard ChangeLog entries for source files.  Incidentally
  regenerated files need not have ChangeLog entries.
- By default, insert a copy of the new ChangeLog entries in the CVS
  check-in comments.
- For large systemic changes, make CVS tags before and after the checkin.