Migrating the existing Trac Wiki pages
![](https://secure.gravatar.com/avatar/eba6eb871de2549c7447a8701352cd35.jpg?s=120&d=mm&r=g)
Hi, As part of the plan to stop using Trac for Twisted project management, we need to find a way to migrate / archive the existing wiki pages from here https://twistedmatrix.com/trac/wiki I see 2 options ------------- Option 1 - Migrate to GitHub own Wiki pages I have already done a test migration. You can see an example here Page https://github.com/twisted/twisted/wiki/ReviewProcess History https://github.com/twisted/twisted/wiki/ReviewProcess/_history Pros: * The wiki page edit history is preserved * Wiki has a separate repo * The wiki can be now edited with Git * GitHub Wiki supports RST or Markdown format Cons: * GitHub Wiki has no support for Trac Wiki format.. so we need some sort of conversion * Continues to depend more on GitHub --------------- Option 2 - Migrate the latest Wiki snapshot to a Python Sphinx based website You can see an example here https://judgegregg.github.io/sphinxwiki/content/pages/ReviewProcess Code is at https://github.com/twisted/twisted.github.io/pull/10 Pros: * Uses Sphinx and we are already familiar with that Cons: * The revision history is not visible from the web page (still can be available via the source repo) --------- I am for using option 1, but only as an "archive". I am also able to allocate all the required resources in order to make this happen :) Any wiki page of value, should be migrated to our official documentation at https://docs.twistedmatrix.com For example, there is this PR to migrate the security wiki page to our official documentation https://github.com/twisted/twisted/pull/1712 And if that PR is reviewed, I plan to migrate the ReviewProcess wiki page next. I am against option 2. We already have https://docs.twistedmatrix.com using Sphinx, hence I am not happy with having 2 separate Sphinx sites for Twisted. ---------- What do **you** think? You can send your feedback over email or over IRC or Gitter. Thanks -- Adi Roiban
![](https://secure.gravatar.com/avatar/e1554622707bedd9202884900430b838.jpg?s=120&d=mm&r=g)
There’s an important “con” missing here which I think makes this Option 1 a non-starter: in order to not break links to the existing website, we need to host all the pages (or at least have redirect mappings set up) on our existing website anyway. Having no process to update those mappings means we need stub wiki pages to stick around forever.
![](https://secure.gravatar.com/avatar/e1554622707bedd9202884900430b838.jpg?s=120&d=mm&r=g)
Oops, hit “send” too soon, the concluding idea was this: Given that we need to have some kind of static website pipeline anyway, it seems like a waste to have the static website pipeline for maintaining redirects or copies and a Github wiki site. Furthermore, I don’t actually think we get much value out of the wiki as a wiki: there’s not a lot of collaborative editing that goes on there. It’s mostly just the toolchain we happen to use for the website. There’s also a lot of duplication between the wiki and the official docs, and I’d like to see them get gradually refactored, which would be easier if they were both in git repos. So the functionality of the Github wiki feels somewhere between “pointless” and “counterproductive” to me; it just allows us to keep having the same problem we’ve had for a while. i.e.: "where does this go, should I put it on the wiki or in the docs”, which is exacerbated by wanting to use a different toolchain depending on the amount of investment the author wants to make in the content. If everything goes into the same toolchain, via PRs, then the only question is “where is it better for this to go for the reader”, which is the question we should be asking :). OK… I think that’s actually my whole point this time. -g
![](https://secure.gravatar.com/avatar/e1554622707bedd9202884900430b838.jpg?s=120&d=mm&r=g)
There’s an important “con” missing here which I think makes this Option 1 a non-starter: in order to not break links to the existing website, we need to host all the pages (or at least have redirect mappings set up) on our existing website anyway. Having no process to update those mappings means we need stub wiki pages to stick around forever.
![](https://secure.gravatar.com/avatar/e1554622707bedd9202884900430b838.jpg?s=120&d=mm&r=g)
Oops, hit “send” too soon, the concluding idea was this: Given that we need to have some kind of static website pipeline anyway, it seems like a waste to have the static website pipeline for maintaining redirects or copies and a Github wiki site. Furthermore, I don’t actually think we get much value out of the wiki as a wiki: there’s not a lot of collaborative editing that goes on there. It’s mostly just the toolchain we happen to use for the website. There’s also a lot of duplication between the wiki and the official docs, and I’d like to see them get gradually refactored, which would be easier if they were both in git repos. So the functionality of the Github wiki feels somewhere between “pointless” and “counterproductive” to me; it just allows us to keep having the same problem we’ve had for a while. i.e.: "where does this go, should I put it on the wiki or in the docs”, which is exacerbated by wanting to use a different toolchain depending on the amount of investment the author wants to make in the content. If everything goes into the same toolchain, via PRs, then the only question is “where is it better for this to go for the reader”, which is the question we should be asking :). OK… I think that’s actually my whole point this time. -g
participants (2)
-
Adi Roiban
-
Glyph