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.