= Wiki pages to be included in a release = [[PageOutline(2-3)]] == 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. === Page list ''This list only provided for convenience. See [source:/trunk/contrib/checkwiki.py#latest 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 [milestone:0.13] release, and the name of the person who proof-read and possibly updated/corrected that page. ||= Page ||= Proof-read ||= Comments || || CamelCase || || || || InterMapTxt || || || || InterTrac || || || || InterWiki || || || || RecentChanges || || || || TitleIndex || || || || TracAccessibility || || || || TracAdmin || || || || TracBackup || || || || TracBrowser || || || || TracCgi || || || || TracChangeset || || || || TracEnvironment || || || || TracFastCgi || || || || TracFineGrainedPermissions || || || || TracGuide || || || || TracIni || || || || TracInstall || || || || TracInterfaceCustomization || || || || TracImport || || || || TracLinks || || || || TracLogging || || || || TracModPython || || || || TracModWSGI || || || || TracNavigation || || || || TracNotification || || || || TracPermissions || || || || TracPlugins || || || || TracQuery || || || || TracReports || || || || 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 [milestone:0.13] release (still under development). == Life-cycle of the default wiki pages #lifecycle In the following, we call "0.X" the current stable version. === Status quo The TracGuide pages present at the toplevel of the project correspond to the current stable version 0.X. 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 and major releases (see [#sync] below) So a "backup" of the toplevel pages for the previous major release is present in the wiki page hierarchy below `0.(X-1)/`. Likewise, upcoming changes are prepared below the `0.(X+1)/` page hierarchy (dev pages). Pages are created there as needed, when a new feature or change in behavior needs to be documented. === When migrating to a new major release When the time of a new major `0.(X+1)` release is getting near (usually at the time of the beta), the toplevel pages are copied to X/... 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 Trac `0.X`. The changes that occurred in a toplevel page since the corresponding `0.(X+1)/` page has been created are eventually ported, if those changes are also relevant for the new major version. Then the `0.(X+1)/` 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 `0.(X+1)` pages won't be touched anymore until we'll prepare the migration to the `0.(X+2)` release and make a "backup" of the default pages below `0.(X+1)/` (thereby overwriting the old dev pages). The `0.(X+2)/` dev pages can be created anytime after the `0.(X+1)` release. === How to maintain the default wiki pages in sync? === #sync ''the following section corresponds to the 0.11 / 0.12 period; need to be updated to take advantage of the Mercurial mirrors'' 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. Here's how to set up such an environment using [http://www.selenic.com/mercurial/wiki Mercurial]: ==== Initial Setup ==== {{{ $ svn checkout http://svn.edgewall.org/repos/trac/branches/0.11-stable/ guide-0.11 $ cd guide-0.11 $ hg init $ cp /tmp/trac.hgignore .hgignore $ hg addremove $ hg commit -m "Start sync with branch 0.11-stable [T70xx]" $ (cd trac/wiki/default-pages; \ python ../../../contrib/checkwiki.py -d; dos2unix *) $ hg branch wiki-guide # (1) $ hg commit -m "Those are the un-processed changes from t.e.o wiki" $ hg update -C 0 # (2) $ hg branch repo-guide # (3) $ hg merge wiki-guide }}} Notes: 1. mark the future commit to be on named branch "wiki-guide", the symbolic name for the branch tracking the raw changes made by contributors in the t.e.o wiki 2. switch back to revision '''0''', the one which was in sync with the svn branch 3. mark the future commit to be on named branch "repo-guide", the symbolic name for the branch tracking the changes we will commit in the svn branch Now at this point, carefully review the changes and revert everything you don't want to see merged in the repository. This is the tedious part, but once you've taken a decision to not merge some changes, you won't be asked to take this decision over and over again in ''future'' merges. Once you're happy with how the changes look like, commit them: ==== Commit Changes ==== {{{ $ hg ci -m "Merged contributions (2008-05-08)" $ svn ci -m "TracGuide [milestone:0.11]: sync changes from the wiki (2008-05-08)" }}} While there's a timestamp anyway associated to the changeset, I find it convenient to put the date prominently in the commit message as well. Now, the interesting things begin. Next time you decide to sync, things will be quite easy: ==== Repeat Merge ==== {{{ $ cd guide-0.11 $ hg update -C wiki-guide $ (cd trac/wiki/default-pages; \ python ../../../contrib/checkwiki.py -d; dos2unix *) $ hg ci -m "Downloaded changes 2008-05-09" $ hg update -C repo-guide $ hg merge wiki-guide }}} At this point, you will have only the ''new'' changes in your repository. Review them. If there's a need to "forget" some changes that only make sense on t.e.o, you can use `hg revert trac/wiki/default-pages/TracTickets`. If there's a typo or a wrong information, then take this occasion to fix it in the Wiki itself, then [#RepeatMerge restart the above procedure] (back on the "wiki-guide" branch, get new changes you just did on t.e.o, commit, switch to "repo-guide" and merge again). Once you're happy, [#CommitChanges commit the changes] both locally on the "repo-guide" integration branch and on the 0.11-stable branch. Also, in the (rare) event of a Wiki page move, this has to be tracked manually both at the svn and at the hg level, e.g.: {{{ $ cd trac/wiki/default-pages $ svn mv TracWikiMacros WikiMacros $ hg mv --after TracWikiMacros WikiMacros }}} New pages as well, once they have been added to the checkwiki.py script and downloaded: {{{ $ cd trac/wiki/default-pages $ svn add TracVersionControl $ hg add TracVersionControl }}} '''Note:''' as I went through all those steps again, I noticed that there are actually quite few discrepancies at this point (i.e. near 0.11rc time) between the wiki guide and the default-pages in the repository. This is not always the case, particularly when we're quite advanced in the release cycle of a new version and the online guide still documents the previous stable version. At those times, the above method is far from overkill, quite the contrary it makes it relatively easy to grab the useful contributions from the Wiki. Note also that this method is scalable, and that it can easily be used for tracking ''several'' sources. For [milestone:0.12], we could track the toplevel changes ("wiki-guide" branch in the above), as well as the 0.12 specific pages (0.12/..., in another "wiki-0.12-guide" branch).