devel-guidelines.txt

DEVELOPMENT GUIDELINES
======================


Where to commit:
----------------

Every now and then, the discussion comes up about what can go in the
r-patched (i.e. x.y.z with z >= 1). Here's a preliminary set of
guidelines:

DO fix simple bugs
DO NOT fix bugs that require extensive modification
DO NOT fix exotic bugs that haven't bugged anyone
DO make small enhancements if they are badly needed
DO NOT let one user decide what is badly needed
DO fix configuration for broken platforms
DO NOT break functioning platforms in the process

DO NOT fix things that are not broken
DO NOT restructure code
DO NOT add experimental code
DO NOT modify the API (unless absolutely sure it is buggy)
DO NOT change defaults without a *very* good reason

DO clarify documentation
ONLY add or modify examples if needed for clarification
DO NOT reword messages

DO NOT modify regression tests (except if they were buggy)
Be very careful in adding regression tests and consider using them
  in R-devel only at first.

Notice that addition of new functions and arguments constitutes API
modification. The rationale for not allowing this is that packages
that use new features may become dependent on R >= x.y.z, making all
their dependents unusable with older R installations.

---

For r-devel i.e. what becomes x.y.0 releases only one rule seems
necessary:

DO NOT add code that cannot become reasonably complete by the next release.


[Obviously none of the above rules are carved in stone, and all are
subject to interpretation in actual cases.]


Removing functions:
-------------------

Making a function/feature defunct MUST happen at a minor (x.y.0) release.
Deprecation CAN happen for a branch release.
Deprecation MUST precede making something defunct.

See ?Deprecated and ?Defunct for the practical mechanisms


Recommended packages:
---------------------

Maintainers should avoid making changes that are incompatible with the
API of the current release branch and, as far as possible, also with
the R-oldrelease branch.

The version that goes into the release will be the version that is
current on CRAN at Feature Freeze, i.e. when the version changes to
"beta". This happens at T-14 for ".0" releases and at T-10 for patch
releases. Accordingly, the packages should be uploaded in a stable
state well before those times.

Testing
-------

There is a hierarchy of test targets: see tests/README.  It is 
recommended that

	   make check-devel

is run before committing code changes.


Building with recommended packages:
-----------------------------------

The current set of recommended packages for the current development
version are placed in a subdirectory of CRAN/src/contrib. The
instructions for building with recommended packages are as follows: 

1) Go to the top directory of the source tree
2) run tools/rsync-recommended to populate
   $(top_srcdir)/src/library/Recommended
3) go to the top build directory
4) configure, make

Configure will protest if you haven't fetched the recommended
packages. To build without them, use

path/to/configure --without-recommended-packages

You can rerun tools/rsync-recommended later without reconfiguring;
Make should find the new packages. If you have a local CRAN mirror,
you can set the environment variable CRAN_RSYNC to point to that
instead of to cran.r-project.org:CRAN

"make dist" will create the R-2.x.y tarball, with the
src/library/Recommended directory already populated so [unpack,
configure, make, make install] should work for end users.

"make install" puts everything in place, including recommended
packages.