| 86 | | 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. |
| | 94 | We use a secondary DVCS for doing the sync, edit and merge. |
| | 95 | For example, in the repos:cboos.hg repository: |
| | 96 | - repos:cboos.hg:trac-guide-teo-0.12-prefix contains the snapshots of the raw content of the [[0.12/]] pages, as obtained via: |
| | 97 | {{{ |
| | 98 | $ cd 0.12-stable/trac/wiki/default-pages |
| | 99 | $ python ../../../contrib/checkwiki.py -d -C -p 0.12 |
| | 100 | }}} |
| | 101 | - 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. |
| | 102 | |
| | 103 | Once the initial setup is done, all what is needed is usually: |
| | 104 | - get a new batch of changes from t.e.o |
| | 105 | - inspect the changes, if there's anything that need to be fixed, change it in the wiki, iterate |
| | 106 | - commit on `trac-guide-teo-0.12-prefix` |
| | 107 | - switch to `trac-guide-0.12`, merge from `0.12-stable`, merge from `trac-guide-teo-0.12-prefix` |
| | 108 | - commit in svn |
| | 109 | |
| | 110 | === Migrating to a new major release |
| | 111 | |
| | 112 | 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. |
| | 113 | 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 . |
| | 114 | |
| | 115 | 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. |
| | 116 | |
| | 117 | Then the `X/` pages are copied to toplevel, with the appropriate change in the warning banner. |
| | 118 | |
| | 119 | All toplevel pages are reviewed and updated as needed for the new version `X`. |
| | 120 | |
| | 121 | 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). |
| | 122 | |
| | 123 | The `(X+1)/` dev pages can be created anytime after the `X` release. |
| 91 | | 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. |
| 92 | | 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`. |
| 93 | | |
| 94 | | 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. |
| 95 | | |
| 96 | | Then the `0.(X+1)/` pages are copied to toplevel, with the appropriate change in the warning banner. |
| 97 | | |
| 98 | | All toplevel pages are reviewed and updated as needed for the new version X. |
| 99 | | |
| 100 | | 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). |
| 101 | | |
| 102 | | The `0.(X+2)/` dev pages can be created anytime after the `0.(X+1)` release. |
| 103 | | |
| 104 | | === How to maintain the default wiki pages in sync? === #sync |
| 105 | | ''the following section corresponds to the 0.11 / 0.12 period; need to be updated to take advantage of the Mercurial mirrors'' |
| 108 | | Here's how to set up such an environment using [http://www.selenic.com/mercurial/wiki Mercurial]: |
| 109 | | ==== Initial Setup ==== |
| 110 | | {{{ |
| 111 | | $ svn checkout http://svn.edgewall.org/repos/trac/branches/0.11-stable/ guide-0.11 |
| 112 | | $ cd guide-0.11 |
| 113 | | $ hg init |
| 114 | | $ cp /tmp/trac.hgignore .hgignore |
| 115 | | $ hg addremove |
| 116 | | $ hg commit -m "Start sync with branch 0.11-stable [T70xx]" |
| 117 | | $ (cd trac/wiki/default-pages; \ |
| 118 | | python ../../../contrib/checkwiki.py -d; dos2unix *) |
| 119 | | $ hg branch wiki-guide # (1) |
| 120 | | $ hg commit -m "Those are the un-processed changes from t.e.o wiki" |
| 121 | | $ hg update -C 0 # (2) |
| 122 | | $ hg branch repo-guide # (3) |
| 123 | | $ hg merge wiki-guide |
| 124 | | }}} |
| 125 | | Notes: |
| 126 | | 1. mark the future commit to be on named branch "wiki-guide", the symbolic |
| 127 | | name for the branch tracking the raw changes made by contributors in |
| 128 | | the t.e.o wiki |
| 129 | | 2. switch back to revision '''0''', the one which was in sync with the svn branch |
| 130 | | 3. mark the future commit to be on named branch "repo-guide", the symbolic |
| 131 | | name for the branch tracking the changes we will commit in the svn branch |
| | 130 | We do that pretty much the same way we already described above for [#sync012 0.12]. |
| 133 | | 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. |
| | 132 | For example, in the repos:cboos.hg repository: |
| | 133 | - repos:cboos.hg:trac-guide-teo contains the snapshots of the raw content of the toplevel pages, as obtained via: |
| | 134 | {{{ |
| | 135 | $ cd trunk/trac/wiki/default-pages |
| | 136 | $ python ../../../contrib/checkwiki.py -d -C |
| | 137 | }}} |
| | 138 | - 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. |
| 135 | | Once you're happy with how the changes look like, commit them: |
| 136 | | ==== Commit Changes ==== |
| 137 | | {{{ |
| 138 | | $ hg ci -m "Merged contributions (2008-05-08)" |
| 139 | | $ svn ci -m "TracGuide [milestone:0.11]: sync changes from the wiki (2008-05-08)" |
| 140 | | }}} |
| 141 | | 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. |
| | 140 | Once the initial setup is done, all what is needed is usually: |
| | 141 | - get a new batch of changes from t.e.o |
| | 142 | - inspect the changes, if there's anything that need to be fixed, change it in the wiki, iterate |
| | 143 | - commit on `trac-guide-teo` |
| | 144 | - switch to `trac-guide-1.0`, merge from `trunk`, merge from `trac-guide-teo` |
| | 145 | - commit in svn |
| 143 | | Now, the interesting things begin. Next time you decide to sync, things will be quite easy: |
| 144 | | ==== Repeat Merge ==== |
| 145 | | {{{ |
| 146 | | $ cd guide-0.11 |
| 147 | | $ hg update -C wiki-guide |
| 148 | | $ (cd trac/wiki/default-pages; \ |
| 149 | | python ../../../contrib/checkwiki.py -d; dos2unix *) |
| 150 | | $ hg ci -m "Downloaded changes 2008-05-09" |
| 151 | | $ hg update -C repo-guide |
| 152 | | $ hg merge wiki-guide |
| 153 | | }}} |
| 154 | | At this point, you will have only the ''new'' changes in your repository. |
| 155 | | 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`. |
| 156 | | 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). |
| 157 | | |
| 158 | | Once you're happy, [#CommitChanges commit the changes] both locally on the "repo-guide" integration branch and on the 0.11-stable branch. |
| 159 | | |
| 160 | | 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.: |
| 161 | | {{{ |
| 162 | | $ cd trac/wiki/default-pages |
| 163 | | $ svn mv TracWikiMacros WikiMacros |
| 164 | | $ hg mv --after TracWikiMacros WikiMacros |
| 165 | | }}} |
| 166 | | |
| 167 | | New pages as well, once they have been added to the checkwiki.py script and downloaded: |
| 168 | | {{{ |
| 169 | | $ cd trac/wiki/default-pages |
| 170 | | $ svn add TracVersionControl |
| 171 | | $ hg add TracVersionControl |
| 172 | | }}} |
| 173 | | |
| 174 | | '''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. |
| 175 | | |
| 176 | | 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. |
| 177 | | |
| 178 | | 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). |
| 179 | | |
| | 147 | Note that porting changes from 0.12 to 1.0 happens quite naturally when we port over the changes from [source:branches/0.12-stable] to [source: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. |
