| Version 37 (modified by , 13 years ago) ( diff ) |
|---|
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.
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 0.13 release, and the name of the person who proof-read and possibly updated/corrected that page.
Status
Next review will be for the 0.13 release (still under development).
Life-cycle of the default wiki pages
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?
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 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:
- 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
- switch back to revision 0, the one which was in sync with the svn branch
- 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 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, 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 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).
Attachments (1)
-
trac.hgignore
(124 bytes
) - added by 16 years ago.
.hgignore file I use for mixed svn/hg trac working copies
Download all attachments as: .zip
