|
|
| Line 1: |
Line 1: |
| <!-- -*- mode: auto-fill; -*- -->
| | '''WARNING: content on ''this'' wiki might be wiped without notice! (read on)''' |
|
| |
|
| = Welcome to the Debian Development Wiki =
| | '''wiki.debian.org is still the live Debian Wiki service: please continue using it.''' |
|
| |
|
| == Getting started ==
| | This [https://www.mediawiki.org MediaWiki] install is intended to eventually replace the current MoinMoin-based wiki running on [https://wiki.debian.org/ wiki.debian.org] as a support and documentation resource for the [https://www.debian.org Debian project]. ''This has not yet happened''. |
|
| |
|
| Debian is converting its wiki to Mediawiki. If you are seeing this
| | The project is in very early stages. You can get involved! Discussion happens on the [https://lists.debian.org/debian-wiki/ debian-wiki mailing list] and the {{DebianIRC|debian-wiki}} channel on the OFTC IRC network. The current state and summary should be recorded on the live wiki's [https://wiki.debian.org/DebianWiki/WikiRevamp WikiRevamp page]. |
| page it means you have succesfully installed the WikiDev container
| |
| image of MediaWiki, which contains a few completely new pages (like
| |
| the one you are reading now) plus a small number Pages that are
| |
| downloaded from the old wiki, and converted on-the-fly from MoinMoin
| |
| to [https://www.mediawiki.org/wiki/Wikitext Wikitext] (see the list
| |
| [[Special:AllPages|here]]). From here on, the MoinMoin wiki, still
| |
| alive at https://wiki.debian.org/, will be referred to as “the
| |
| old wiki”.
| |
| | |
| This page introduces what we're doing and how you can help.
| |
| | |
| === How the development environment is organized ===
| |
| | |
| For the time being, during the process of developing the tools, macros
| |
| and conversions needed for the big conversion from MoinMoin to
| |
| Wikitext, we are using a few software repositories on Salsa to
| |
| maintain the tools.
| |
| | |
| There are three repositories responsible for most of the conversion
| |
| work:
| |
| | |
| ==== 1. debwiki-dev-pages ====
| |
| | |
| The page you are reading can be found in the
| |
| [https://salsa.debian.org/wiki-team/debwiki-dev-pages <code>debwiki-dev-pages</code>] | |
| repository on Salsa. It contains pages for the new wiki (this one)
| |
| ''that are not in the old wiki''. It also contains several templates and
| |
| macros which on the
| |
| [https://www.mediawiki.org/wiki/MediaWiki MediaWiki] platform is
| |
| saved as ''Pages''. In fact, everything in Mediawiki is Pages, not only
| |
| user content, but also Templates, Forms and other components used to
| |
| produce the final site. If you'd like to work with editing pages and/or
| |
| creating new content for the new wiki this is where you want to be
| |
| working.
| |
| | |
| ==== 2. debwiki-dev-converter ====
| |
| | |
| The software components doing the under-the-hood conversion work
| |
| can be found in the
| |
| [https://salsa.debian.org/wiki-team/debwiki-dev-converter <code>debwiki-dev-converter</code>]
| |
| repository. Its main function is to convert Debian's old MoinMoin wiki
| |
| markup to MediaWiki XML dumps, and will be used when the time comes to
| |
| do the grand conversion. Now, we want to stress test it, find issues
| |
| and see if improvements are needed, and that is one of the purposes of
| |
| this wiki container.
| |
| | |
| At the moment the <code>debwiki-dev-converter</code> also is responsible for
| |
| converting a bunch of sample documents from the old wiki to the new
| |
| one, but this functionality will likely be separated out to its own
| |
| repository in the future ('''Andrew?'''), so we can keep the conversion
| |
| tools separate from the pages to convert. This will also make the
| |
| <code>debwiki-dev-converter</code> software generally usable for other
| |
| projects that want to do the same conversion.
| |
| | |
| If you are interested in working on the software that does the
| |
| under-the-hood conversion to Wikitext, you need to work on this
| |
| repository, and be in close contact with the maintainers.
| |
| | |
| ==== 3. moinmoin_onlinereader ====
| |
| | |
| Behind the scenes is the
| |
| [https://salsa.debian.org/AndrewSayers/moinmoin_onlinereader <code>moinmoin_onlinereader</code>],
| |
| this is a software component that does an on-the-fly conversion of the Moin source to a
| |
| [https://pandoc.org/ Pandoc]
| |
| [https://pandoc.org/using-the-pandoc-api.html Abstract Syntax Tree]
| |
| (AST) from the live <code>wiki.debian.org</code> site. The
| |
| <code>moinmoin_onlinereader</code> library logs in to the wiki and
| |
| asks <code>Pandoc</code> to parse the rendered HTML and render it as
| |
| wikitext. When the online reader logs into the Debian wiki, it is
| |
| using your credentials, that you used to get this container running.
| |
| | |
| Unless you are interested in this part of the migration process, this
| |
| component is unlikely to be of interest to you.
| |
| | |
| === How to work on these repositories ===
| |
| | |
| The workflow for working with all of the above git repositories is the
| |
| typical <code>git</code> workflow used in most open source projects, but we
| |
| detail it here in case you need a reminder.
| |
| | |
| You need an account on [https://salsa.debian.org/ Salsa]. Once logged
| |
| on, you can make a ''fork'' of the repository you want to work on.
| |
| Clone your fork to your computer and switch to a branch, optimally
| |
| named something relevant in relation to the work you want to do.
| |
| | |
| When done with your work, push the branch back to your repo fork on
| |
| Salsa, and then write and submit a Merge Request (MR). Remember that
| |
| your description must enable the maintainer to quickly review what
| |
| your MR is all about, so be descriptive. Also, remember that ''atomic
| |
| merge requests'' are much better than huge ones, and more likely to be
| |
| accepted quickly and without a lot of back-and-forth with the
| |
| maintainer. Be aware that a MR is like a PR on other platforms like
| |
| Github, but it also adds a merge commit to the repo when it's accepted.
| |
| | |
| Finally, please be aware that it can take up to a few days for your
| |
| merge request to get through manual review, so be patient!
| |
| | |
| == Join us on Internet Relay Chat ==
| |
| | |
| If you'd like a real-time chat with developers and contributors to the
| |
| new wiki, we have an IRC channel on OFTC named `#debian-wiki`, and try
| |
| to have a presence there. You are encourged to join. Use any IRC
| |
| client of your choice, or click this link: {{DebianIRC|debian-wiki}},
| |
| which will open an IRC client in your browser.
| |
| | |
| == Keeping this development container up-to-date ==
| |
| | |
| To remind you, when you created this development wiki you pulled an image from
| |
| upstream using <code>podman</code>, like this:
| |
| | |
| <pre>
| |
| podman pull registry.salsa.debian.org/wiki-team/debwiki-dev-container:latest
| |
| </pre>
| |
| | |
| At the moment, the content of this wiki is generated by the conversion
| |
| system described above when upstream builds the container from the
| |
| <code>Dockerfile</code>. The build process quite simply clones the development
| |
| repos onto the image, so when you create the <code>podman</code> container these
| |
| are already embedded in the image.
| |
| | |
| So in order to see updates that have happened, you need to pull a new
| |
| image regularly. Be aware that old images are not deleted by pulling
| |
| new ones, so you still have access to older ones if you so wish, or
| |
| you can remove them using the <code>podman</code> utility (or for example
| |
| <code>cockpit</code> if you are using that).
| |
| | |
| Just to remind you, this is how the container (i.e. the running
| |
| instance of the image) is created:
| |
| | |
| <pre>
| |
| podman run --rm -i \
| |
| -p 8080:80 \
| |
| --name=debwiki-dev-environment \
| |
| debwiki-dev-environment:latest \
| |
| <your-MOINMOIN_SESSION_443_ROOT-value>
| |
| </pre>
| |
| | |
| A detailed description is available in the
| |
| [https://salsa.debian.org/wiki-team/debwiki-dev-environment/-/blob/main/README.md|README] | |
| file of the <code>debwiki-dev-environment</code> repo. But then again you
| |
| probably know all about that since you got here.
| |
| | |
| Now the wiki can be viewed on http://localhost:8080/, like you are
| |
| doing right now.
| |
| | |
| == Links ==
| |
| | |
| These pages are from the old wiki imported to this container image,
| |
| and perhaps of interest to the development work, especially focusing
| |
| on translating files from MoinMoin system to Mediawiki.
| |
| | |
| * The Original Introduction to the [[DebianWiki/WikiRevamp|WikiRewamp Project]]
| |
| * Other [[DebianWiki/WikiRevamp/OtherConversations|Conversations]]
| |
| * Log of the [[DebianWiki/WikiRevamp/MassEditLog|MassEdit]]
| |
| * [[DebianWiki/WikiRevamp/Recommendations|Recommendations]]
| |
| * A [[DebianWiki/WikiRevamp/TestPage|Testpage]] with a variety of Wikitext code.
| |
|
| |
|
| | For examples of ideas we're working on, see [[Category:Example]]. |
