Wiki pages to be included in a release

Review

This page is used to keep track of the informal review process of the default pages, which happens every once in a while, usually shortly before a new major release.

See also the discussion in 0.12#ReviewGuidelines.

Page list

This list only provided for convenience. See checkwiki.py​ for the official list of wiki pages to be included in releases.

The following table lists the pages that will be included in the next 1.0 release, and the name of the person who proof-read and possibly updated/corrected that page.

Page	Proof-read	Comments
CamelCase
InterMapTxt
InterTrac
InterWiki
PageTemplates
RecentChanges
TitleIndex
TracAccessibility
TracAdmin
TracBackup
TracBatchModify
TracBrowser
TracCgi
TracChangeset
TracEnvironment
TracFastCgi
TracFineGrainedPermissions
TracGuide
TracImport
TracIni
TracInstall
TracInterfaceCustomization
TracLinks
TracLogging
TracModPython
TracModWSGI
TracNavigation
TracNotification
TracPermissions
TracPlugins
TracQuery
TracReports
TracRepositoryAdmin
TracRevisionLog
TracRoadmap
TracRss
TracSearch
TracStandalone
TracSupport
TracSyntaxColoring
TracTickets
TracTicketsCustomFields
TracTimeline
TracUnicode
TracUpgrade
TracWiki
TracWorkflow
WikiDeletePage
WikiFormatting
WikiHtml
WikiMacros
WikiNewPage
WikiPageNames
WikiProcessors
WikiRestructuredText
WikiRestructuredTextLinks
WikiStart

Status

Next review will be for the 1.0 release (in beta).

Life-cycle of the default wiki pages

A "backup" of the toplevel pages for the previous major releases is present in the wiki page hierarchy 0.11/, 0.12/.

The toplevel pages (TracGuide and related) correspond to the documentation for the current stable release (1.0) and the minor maintenance releases (1.0.x).

Likewise, upcoming changes will be prepared below the 1.1/ page hierarchy (dev pages). Pages are created there as needed, when a new feature or change in behavior needs to be documented, the first version being a copy of the content of the corresponding toplevel page.

Life-cycle of the wiki pages for Trac 0.12 (LTS)

The TracGuide pages for 0.12/ are not likely to change much, but just in case…

Their content is usually matching the one which has been shipped in the corresponding release, except for:

• a banner mentioning the current version and linking to the page corresponding to the previous release (e.g. for TracWiki: Note: this page documents the 0.12 version of Trac, see 0.11/TracWiki if you need the previous version)
• the edits users have made in the meantime, which will be reviewed and integrated in the next minor releases 0.12.x.

How to maintain the 0.12 wiki pages in sync?

We use a secondary DVCS for doing the sync, edit and merge. For example, in the repos:cboos.hg repository:

• repos:cboos.hg:trac-guide-teo-0.12-prefix contains the snapshots of the raw content of the 0.12/ pages, as obtained via:

  $ cd 0.12-stable/trac/wiki/default-pages
  $ python ../../../contrib/checkwiki.py -d -C -p 0.12
  

• repos:cboos.hg:trac-guide-0.12 is the integration branch for the changes from t.e.o; changes that should not been merged in are discarded (once), like the version specific banner, the static content replacing macro expansions, etc.

Once the initial setup is done, all what is needed is usually:

• get a new batch of changes from t.e.o
• inspect the changes, if there's anything that need to be fixed, change it in the wiki, iterate
• commit on trac-guide-teo-0.12-prefix
• switch to trac-guide-0.12, merge from 0.12-stable, merge from trac-guide-teo-0.12-prefix
• commit in svn

Migrating to a new major release

When the time of a new major release X is getting near (usually at the time of the beta), the toplevel pages are copied to (X-1)/... as a backup. Some care should be taken about replacing the dynamic content found in TracAdmin, TracIni, TracSyntaxColoring (starting with 0.12) and WikiMacros by the output generated by the previous version of Trac .

The changes that occurred in a toplevel page since the corresponding X/ page has been created are eventually ported, if those changes are also relevant for the new major version.

Then the X/ pages are copied to toplevel, with the appropriate change in the warning banner.

All toplevel pages are reviewed and updated as needed for the new version X.

The X/ pages won't be touched anymore until we'll prepare the migration to the (X+1)/ release and make a "backup" of the default pages below X/ (thereby overwriting the old dev pages).

The (X+1)/ dev pages can be created anytime after the X release.

How to maintain the default wiki pages in sync?

As some content is only pertinent on t.e.o and not in the packaged docs, downloading new content from t.e.o will lead to repeated merge, so we need a system that can handle them efficiently.

We do that pretty much the same way we already described above for 0.12.

For example, in the repos:cboos.hg repository:

• repos:cboos.hg:trac-guide-teo contains the snapshots of the raw content of the toplevel pages, as obtained via:

  $ cd trunk/trac/wiki/default-pages
  $ python ../../../contrib/checkwiki.py -d -C
  

• repos:cboos.hg:trac-guide-1.0 is the integration branch for the changes from t.e.o; changes that should not been merged in are discarded (once), like the version specific banner, the editing caveats, etc.

Once the initial setup is done, all what is needed is usually:

• get a new batch of changes from t.e.o
• inspect the changes, if there's anything that need to be fixed, change it in the wiki, iterate
• commit on trac-guide-teo
• switch to trac-guide-1.0, merge from trunk, merge from trac-guide-teo
• commit in svn

Note that porting changes from 0.12 to 1.0 happens quite naturally when we port over the changes from branches/0.12-stable​ to trunk​, but this happens only in the repository, the toplevel pages on t.e.o won't contain these changes. It might be useful from time to time to do a sync the other way round.