Mailman-Developers February 2013

mailman-developers@python.org

8 participants
24 discussions

by Paul Boddie

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

8 years, 7 months

Re: [Mailman-Developers] Mailman-Developers Digest, Vol 286, Issue 7

by Terri Oda

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

8 years, 7 months

Re: [Mailman-Developers] background on maintaining the documentation (was RE: Mailman-Developers Digest, Vol 286, Issue 9)

by Barry Warsaw

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

8 years, 7 months

Re: [Mailman-Developers] background on maintaining the documentation (was RE: Mailman-Developers Digest, Vol 286, Issue 9)

by Terri Oda

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

8 years, 7 months

background on maintaining the documentation (was RE: Mailman-Developers Digest, Vol 286, Issue 9)

by Chris Cargile

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

8 years, 7 months

Re: [Mailman-Developers] List etiquette - was: Mailman-Developers Digest, Vol 286, Issue 7

by Mark Sapiro

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

8 years, 7 months

Re: [Mailman-Developers] Mailman-Developers Digest, Vol 286, Issue 7

by Paul Boddie

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

8 years, 7 months

Re: [Mailman-Developers] Mailman-Developers Digest, Vol 286, Issue 7

by Chris Cargile

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 > ************************************************** >

8 years, 7 months

Changes to on-line documentation ( was Re: (no subject) )

by Terri Oda

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

8 years, 8 months

Re: [Mailman-Developers] (no subject)

by Barry Warsaw

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

8 years, 8 months

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

2001

2000

1999

1998

1997

Mailman-Developers February 2013