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.

---

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


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.


Detailed release schedule for 2.0.0:
------------------------------------

Sep 6: 

    Declare start of release process. The build process is assumed to
    be essentially in place at this time.

    There is a "grand feature" freeze (minor tweaks can be applied,
    but no wholesale restructuring or API changes). Notice that
    wrapping a package in a namespace is a grand feature, and so is
    meddling with the event loop.

    Package maintainers should start adapting to any changes in base.

    Start making R-2.0.0-alpha.tgz packages automatically available. 

Sep 20:

    Feature freeze, simultaneously on base and recommended packages.
    It is assumed that all recommended packages pass their checks at
    this point. The API should not be touched.
    
    Start making R-2.0.0-beta.tgz packages automatically available. 


Sep 27:

    Code freeze. Only critical and/or trivial bugs fixed from this
    time onwards. Configure/make should only be touched in
    emergencies. 

Oct 4:

    Release.