Hello,
This is really just a quick mail to let you know that I haven't forgotten
about my promise to look into migrating the Wiki content to MoinMoin. As
always, you can monitor the status of the work here:
http://hgweb.boddie.org.uk/ConfluenceConverter/
I aim to upload a snapshot of the translated content to a demonstration site
(as I did before) in the next few days, and hopefully will have improved the
output a bit by then. Although I have mostly been focusing on the old
Confluence Wiki markup in the past couple of days, I think that the recent
changes have improved the "fidelity" of the old page revisions somewhat, and
with the new XHTML-style markup being somewhat easier to deal with, I aim to
have parity between the two formats fairly soon.
If there's anything in particular beyond basic content migration that you'd
like to see in MoinMoin, please let me know. The markup mapping page...
http://moinmo.in/ConfluenceConverter/DevelopmentNotes/MarkupMapping
...describes some macros and other features that should be reproduced in the
Moin-based solution, and I've attempted to incorporate existing page comments
(as I described before) and page navigation features, but it would be useful
to know what people currently depend upon so that any extra macros or
extensions can be written.
I'll send another update soon. Thanks for being patient!
Paul
On 02/26/2013 08:23 AM, Chris Cargile wrote:
> At minimum, I think it is important to get confirmation whether the
> confluence snapshot (wiki.list.org) is just a snapshot and we can direct
> our efforts at updating the documentation there? also, on that note, what
> would be the sphinx documentation role in all this and/or how necessary is
> it to understand that system?
You've more or less guessed how it works, but just for confirmation,
here's the deal:
- Each package contains individual setup documentation and doctests
- wiki.list.org contains all other documentation, like the FAQ, larger
user/admin guides, architectural notes, ideas from sprints, GSoC
efforts, etc.
We do "duplicate" setup docs in both places so that they're easier to
find and easier for non-devs to edit in case something's confusing or
inaccurate. There's no specific process for keeping them in sync since
there are relatively few edits.
So in short: for you personally, editing the wiki documentation is the
preferred way to help and you can treat it as the canonical
documentation location. You can, in the case of errors, also submit
merge requests to fix the documentation in the source tree. At some
point, I imagine Paul will tell us the migration is ready to go and
we'll freeze the wiki, but for now go ahead and edit there.
> Finally, for the confluence system, I noticed there is more of a total CMS
> offering vs. just the wiki functionality and wanted to know will the blog
> etc be maintained disparately after we move to a moin system?
Barry just uses the blog functionality as a news area; I'm guessing a
"recent news" page would probably suffice for this. I expect we'll keep
the Confluence wiki around for a little while after the migration, but
since it's a minor hassle to get our license renewed, I expect it will
lapse eventually.
I still have a todo list item reminding me that we'd like a new website
for Mailman 3.0's release (including cleaning up the myriad different
docs available for previous versions) so maybe at that point we'll go
back to using the front page for news updates.
Terri
On Feb 27, 2013, at 02:33 PM, Chris Cargile wrote:
>the Moin system will get us away from the Atlassian licensing hassle AND
>would tie in great for enabling a new website for the MM3 release,
I'm really hoping we can get onto Moin soon, not only for the above good
reasons, but also because of the free software issue, and because -- while
generous -- it's still a big hassle to deal with our Confluence hosting
provider when problems come up. I'm very confident we can find a Moin-based
wiki a good home.
>The documentation is maintained to some level in Atlassian, pythonhosted.org,
>and the bzr repos (, other places?) per package, so Terri explained that
>Atlassian is the main location for how-to's, admin guides, and GSOC stuff.
>Otherwise, for simplicity, the packages have docs and doctests, in the
>individual package themselves
I'm a big fan of having as much documentation in the source repository as
possible. I love a good wiki, but everything needs gardening and
documentation seems better suited for version control systems. Not all
documentation need be testable, but that which can be works great being part
of the source tree. (The current doctest suite is I think of mixed quality;
some of the older doctests conflated too much bad-path testing which makes it
more difficult to read as documentation. I've been migrating much of that to
unittests, in order to improve the readability and good-path flow of the
documentation.)
It's also much easier to review and merge documentation changes via our dvcs
tools.
One thing that's missing is better overview documentation. That's long been
on my list of things to improve.
>Would the merges accepted propogate document changes to the package repos or
>are we referring to a merge against a documents-repo that is somewhere I
>don't know of. I'm still confused on where the sphinx documentation plays
>into it (is that maybe like building javadocs only, instead it does so for
>python, maybe)
The pythonhosted.org (formerly packages.python.org) documentation is generated
from the source tree via `python setup.py build_sphinx`. You can build it and
view it locally the same way. `python setup.py upload_docs` is what gets the
new documentation uploaded, but I've just created a project on readthedocs.org
so I think we should migrate there as our primary online documentation
source. The nice thing is that gets automatically updated when we push
updates to lp:mailman (i.e. trunk).
Cheers,
-Barry
On 13-02-27 12:33 PM, Chris Cargile wrote:
> the Moin system will get us away from the Atlassian licensing hassle
> AND would tie in great for enabling a new website for the MM3 release,
Um... Chris, you do realize that we're experience software developers
working on a project under the banner of the free software foundation?
We're reasonably familiar with licensing issues and how they relate to
mailman! The message you sent (which I've mostly snipped) is not only
un-timely at this point so long after the decision about switching was
made but also seems a little patronizing in context.
> Would the merges accepted propogate document changes to the package
> repos or are we referring to a merge against a documents-repo that is
> somewhere I don't know of. I'm still confused on where the sphinx
> documentation plays into it (is that maybe like building javadocs
> only, instead it does so for python, maybe)
There is a docs directory in each project. There is no separate docs repo.
Mailman's is here:
https://bazaar.launchpad.net/~mailman-coders/mailman/3.0/files/head:/src/ma…
Postorius' is here:
https://bazaar.launchpad.net/~mailman-coders/postorius/trunk/files/head:/sr…
and I don't have a link for Hyperkitty's handy but I'm sure you can find
it yourself.
And now my turn to border on patronizing: My recommendation is that as
a new contributor, you should really stick to editing the wiki until you
have a sense of what you're doing and let the devs maintain the
documentation for their own packages.
Terri
thanks guys - that helps me get going with things..like documentation
probably should, huh? :)
>If there is any functionality that you are wondering about, by all means
>provide a link to an example of its usage and I'll try and give an opinion
on
>whether it will be easily supported or not. Generally, the border between
>Wiki and CMS territory is vague (a Wiki is a form of CMS, after all) and it
>can be quite straightforward to add functionality regarded as CMS-specific
to
>Moin.
>Paul
the Moin system will get us away from the Atlassian licensing hassle AND
would tie in great for enabling a new website for the MM3 release, - it
would be cool, IMO, if we got to explore the RSS feature's (
http://moinmo.in/MoinMoinSyndication) working since we could generate
recent changes outputting onto a feed, and from there, either give the RSS
page some nice CSS or display the feed on the new site main-page if it was
being served up separately from the moin system. I also checked using the
w3c validator and moin outputs its pages in valid-xhtml mark-up so that's
good for accessibility, which seems like a good goal for Mailman too,
seeing as its role is a communications medium
so +++1 for the moin cms transfer (/RSS?) - I don't have much familiarity
with moin blogspaces, but it'll work fine I bet
>>So I interpret your question as being whether the documentation on the
Wiki is
>>just a snapshot of some documentation maintained elsewhere or whether the
>>work is being done on the Wiki itself.
The documentation is maintained to some level in Atlassian, pythonhosted.org,
and the bzr repos (, other places?) per package, so Terri explained that
Atlassian is the main location for how-to's, admin guides, and GSOC stuff.
Otherwise, for simplicity, the packages have docs and doctests, in the
individual package themselves
on Tue, 26 Feb 2013 10:38 Terri Oda wrote:
> At minimum, I think it is important to get confirmation whether the
> confluence snapshot (wiki.list.org) is just a snapshot and we can direct
> our efforts at updating the documentation there? also, on that note, what
> would be the sphinx documentation role in all this and/or how necessary is
> it to understand that system?
>>You can, in the case of errors, also submit
>>merge requests to fix the documentation in the source tree. At some
>>point, I imagine Paul will tell us the migration is ready to go and
>>we'll freeze the wiki, but for now go ahead and edit there.
Would the merges accepted propogate document changes to the package repos
or are we referring to a merge against a documents-repo that is somewhere I
don't know of. I'm still confused on where the sphinx documentation plays
into it (is that maybe like building javadocs only, instead it does so for
python, maybe)
r/Chris
It helps greatly if replies to digests are given a meaningful subject
and do not quote irrelevant parts of the digest.
--
Mark Sapiro <mark(a)msapiro.net> The highway is for gamblers,
San Francisco Bay Area, California better use your sense - B. Dylan
On Tuesday 26 February 2013 16:23:56 Chris Cargile wrote:
>
> - IOW, could we assume the wiki.list.org is the de facto location for
> overall MM3 documentation and that bzr or pythonhosted.org would be where
> the individual component's documentation should be maintained for now?
I'll stay out of any discussion about Mailman documentation because I'm not
really involved in Mailman development.
> At minimum, I think it is important to get confirmation whether the
> confluence snapshot (wiki.list.org) is just a snapshot and we can direct
> our efforts at updating the documentation there? also, on that note, what
> would be the sphinx documentation role in all this and/or how necessary is
> it to understand that system?
I'm guessing here that you're referring to the DOC space generally and
documents like the following specifically:
http://wiki.list.org/display/DOC/Mailman+2.1+Members+Manual
So I interpret your question as being whether the documentation on the Wiki is
just a snapshot of some documentation maintained elsewhere or whether the
work is being done on the Wiki itself.
> Finally, for the confluence system, I noticed there is more of a total CMS
> offering vs. just the wiki functionality and wanted to know will the blog
> etc be maintained disparately after we move to a moin system?
My aim is to support blog functionality since it shouldn't be anything
fundamentally different from what Moin does even without extensions. There
seems to be things like activity logs, and Moin doesn't really support
this "out of the box" for each contributor, but I've been meaning to
implement such functionality for Moin anyway.
If there is any functionality that you are wondering about, by all means
provide a link to an example of its usage and I'll try and give an opinion on
whether it will be easily supported or not. Generally, the border between
Wiki and CMS territory is vague (a Wiki is a form of CMS, after all) and it
can be quite straightforward to add functionality regarded as CMS-specific to
Moin.
Paul
To pair with Sandesh's sharing that the python-version-requirement in the
documentation needed updating and to coincide with Paul's (brave :)
commitment, I would like to know what the "must-do"s are, and later more
specifically, the processes for updating the build documentation in its
various places:
- while each component of MM3 )archiver, UI...) should be entitled to its
own separate documentation for modularity and sanity of the developers,
what would be considered the best practices for documentation as a whole?
This is one of my first dives into software development in a
group-oriented/open-source env't but in non-profit organizations I
volunteer-served and administrated, clear and systematic process flows were
helpful (to help me stay focused)
- IOW, could we assume the wiki.list.org is the de facto location for
overall MM3 documentation and that bzr or pythonhosted.org would be where
the individual component's documentation should be maintained for now?
At minimum, I think it is important to get confirmation whether the
confluence snapshot (wiki.list.org) is just a snapshot and we can direct
our efforts at updating the documentation there? also, on that note, what
would be the sphinx documentation role in all this and/or how necessary is
it to understand that system?
Finally, for the confluence system, I noticed there is more of a total CMS
offering vs. just the wiki functionality and wanted to know will the blog
etc be maintained disparately after we move to a moin system?
This is a lot but I'm trying to get to speed - on the fun side, I'm making
my first update to add me on the remote-attendees list for the upcoming
pysprints
Cheers,
Chris
On Mon, Feb 25, 2013 at 6:00 AM, <mailman-developers-request(a)python.org>wrote:
> Send Mailman-Developers mailing list submissions to
> mailman-developers(a)python.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
> http://mail.python.org/mailman/listinfo/mailman-developers
> or, via email, send a message with subject or body 'help' to
> mailman-developers-request(a)python.org
>
> You can reach the person managing the list at
> mailman-developers-owner(a)python.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Mailman-Developers digest..."
>
>
> Today's Topics:
>
> 1. Wiki Migration Update (Paul Boddie)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Mon, 25 Feb 2013 00:01:17 +0100
> From: Paul Boddie <paul(a)boddie.org.uk>
> To: mailman-developers(a)python.org
> Subject: [Mailman-Developers] Wiki Migration Update
> Message-ID: <201302250001.18261.paul(a)boddie.org.uk>
> Content-Type: text/plain; charset="us-ascii"
>
> Hello,
>
> This is really just a quick mail to let you know that I haven't forgotten
> about my promise to look into migrating the Wiki content to MoinMoin. As
> always, you can monitor the status of the work here:
>
> http://hgweb.boddie.org.uk/ConfluenceConverter/
>
> I aim to upload a snapshot of the translated content to a demonstration
> site
> (as I did before) in the next few days, and hopefully will have improved
> the
> output a bit by then. Although I have mostly been focusing on the old
> Confluence Wiki markup in the past couple of days, I think that the recent
> changes have improved the "fidelity" of the old page revisions somewhat,
> and
> with the new XHTML-style markup being somewhat easier to deal with, I aim
> to
> have parity between the two formats fairly soon.
>
> If there's anything in particular beyond basic content migration that you'd
> like to see in MoinMoin, please let me know. The markup mapping page...
>
> http://moinmo.in/ConfluenceConverter/DevelopmentNotes/MarkupMapping
>
> ...describes some macros and other features that should be reproduced in
> the
> Moin-based solution, and I've attempted to incorporate existing page
> comments
> (as I described before) and page navigation features, but it would be
> useful
> to know what people currently depend upon so that any extra macros or
> extensions can be written.
>
> I'll send another update soon. Thanks for being patient!
>
> Paul
>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> Mailman-Developers mailing list
> Mailman-Developers(a)python.org
> http://mail.python.org/mailman/listinfo/mailman-developers
>
>
> ------------------------------
>
> End of Mailman-Developers Digest, Vol 286, Issue 7
> **************************************************
>
First: Sandesh, could you start using relevant subject lines on your
emails? Posting once with no subject looks like a mistake, but posting
repeatedly with no subject is terrible mailing list etiquette and looks
particularly bad when you're hoping to work with people who develop
mailing list software.
It's bad etiquette because it makes it more difficult for people to
prioritize what they read at a glance or find a particular message of
yours if they've thought of some new information and want to go back and
reply later. See more on good subject lines here:
http://mno.org.uk/email-list-etiquette/ (or just do a google search --
lots of sites have different etiquette guidelines, but you'll notice a
lot of commonalities.
On 13-02-21 5:28 AM, Sandesh Agrawal wrote:
> What is the procedure to commit changes in the on-line documentation
> so that i can upload my changes for merge proposal .
>
The documentation that I think you mean can be found under
src/mailman/docs/ in your mailman directory. You might want to read up
a bit on the .rst format, but it's mostly intuitive. If you're not sure
exactly where the bit you want is, try grepping for a longer phrase near
where you want to edit.
If you mean wiki documentation, though, that's separate and not strictly
necessary for a merge proposal, although always recommended!
Terri
On Feb 21, 2013, at 05:19 AM, Sandesh Agrawal wrote:
>I managed to get postorius running after much efforts, and i would
>suggest some minor changes in the documentation given at :
>http://pythonhosted.org/mailman/src/mailman/docs/WebUIin5.html
>
>1. django version required should be changed to 1.4 from >=1.3
>2. "cd dev_setup" is very confusing as there is no directory named
>dev_setup formed. Instead it should be mentioned that developers refer
>the documentation in "/postorius/src/postorius/doc/setup.rst" for
>further setting up of development server.
Hi Sandesh, how would you like to do a merge proposal with your suggested
changes? :)
Cheers,
-Barry