Google Season of Docs 2019 Ideas Page
Mailman is free software for managing electronic mail discussion and e-newsletter lists. Mailman is integrated with the web, making it easy for users to manage their accounts and for list owners to administer their lists. Mailman supports built-in archiving, automatic bounce processing, content filtering, digest delivery, spam filters, and more. Many open source denizens will be familiar with Mailman 2.1, which is used to manage many project mailing lists. All of our current work is on Mailman 3, which was released in 2015, but there's still lots of room for new features and ideas!
Not sure about how GSoD works? Check out the GSoD home page
Aren't familiar with Mailman, the project? We're a friendly, open organization committed to diversity. We subscribe to the Python Code of Conduct. We cooperate on and off with other organizations, most frequently Systers and the Python Software Foundation. Google Season of Docs is a brand new program, so we have no experience with it, but Mailman has been accepted to Google Summer of Code (GSoC) every year from 2012 to 2019 (sometimes under the Python Software Foundation umbrella, mostly as an independent organization), except 2018 when we decided to take a break. Our organization admins Steve and Abhilash are both experienced GSoC mentors, and we have several other experienced mentors who have not yet been able to commit to Season of Docs as "official" mentors, but certainly will chip in to help as they can. Our students have generally been successful in other orgs as well, and Abhilash himself was originally recruited to Mailman as a GSoC intern in 2013.
Note: We've not been accepted yet (nobody has!) We'd love you to contact us as early as possible, and you're certainly welcome to work on our docs outside of GSoD, but we also encourage you to explore other projects too in case our organization is not accepted.
Contents
Getting Started
The GSoD getting started page has some great general GSoD information. Read it first!
Before you ask any questions about how to do anything in git or initialize your repository please read through the git howto and see if that answers your questions.
Recommended Skills
Here's a few skills that will make it easier for you to get started as a Mailman technical writer. The only essential:
Ability to communicate with the Mailman developers. You'll be expected to post to the public mailing lists, ask questions, and describe the work you're doing.
Optional but very helpful (in order of importance):
Familiarity with any version control. We use git on Gitlab, but any experience will help you here.
Python programming. You don't need to know Python, or even how to program, but you are probably going to run into it and you have to be comfortable asking questions if you aren't sure how it works. Python looks a lot like English, but it's not. It's an artificial language with its own idioms and precise, but sometimes non-intuitive, semantics.
Ability to setup a development environment for Mailman. You'll need access to a Linux machine or VM, and we will help you set to it up. We can set up test sites for some tasks, but others will be much easier if you have a working Mailman of your own.
Specific projects may have additional desired skills listed along with them.
What is Mailman Suite?
The previous version, Mailman 2 (like many other mailing list managers) is a single project, tightly integrated. In Mailman 3, we've divided up the code into a number of sub-projects, with the intent of providing a full working site, but also allowing sites to set up their own "dashboards" and archiving systems. We refer to the whole package as "Mailman Suite" and there's a few really important pieces you should know:
Mailman Core - This is the part that actually sends and receives mail and handles subscriber and list information.
Postorius - A web interface for managing Mailman lists (e.g. subscribing, changing preferences)
Hyperkitty - A web interface to access GNU Mailman v3 archives.
There's also a number of smaller projects that provide the glue to make these pieces work well together, or allow them to be used separately.
All the Mailman source is now on GitLab.
GSoD Application Process
Write to Mailman Developers <mailman-developers@python.org>, and tell us you're interested in working on the Mailman documentation for Google Season of Docs. That's it! We'll help you create a documentation proposal, and refine it.
Contacting us
The most successful GSoD students are the ones who work closely with the Mailman team. As you might expect from a group that makes mailing list software, our preferred method of communication is our mailing list, but we also have an IRC channel. Please do not send private messages or emails unless asked to do so or the subject is personal rather than technical, since we get a lot of similar questions and would rather the questions and answers happen in public so everyone can benefit.
Mailing list to use for GSoD discussions: Mailman developers mailing list
- IRC channel: #mailman on irc.freenode.org (you'll need a registered nickname to join this channel.
We expect that everybody will be comfortable with communicating by email, but of course sometimes you want something a little more interactive. Since IRC is a little geeky, we'll seriously consider alternative messaging apps. (No promises, except to consider.)
Writing Your Application
The Introduction to Season of Docs page is the place to start.
This page is still under development, but here are some references that our Summer of Code interns have found useful.
The GSoC student Guide has some great information
Tips for Prospective Google Summer of Code Students (general good advice)
Tips for writing a good GSoC proposal (advice on structuring and composing the document)
Project Ideas
If you have other idea you'd like to propose , please send it to mailman-developers@python.org for discussion! You can also look at the to-do list for Mailman 3.0 here, and see if anything is interesting enough that you would like to work on it through the summer.
Instructions for Migrating from Mailman 2 to Mailman 3
Our biggest lack in documentation is a comprehensive guide for existing Mailman 2 users who wish to switch to Mailman 3. We have some "how to" style guides, but questions on the mailing lists indicate that they're insufficient, with many details that users have to cover.
Additional Requirements
- Local installations of both Mailman 2 and Mailman 3 would be helpful (though not essential) to this task. The mentors would guide both installation, and experimentation to see "what can go wrong". There are other ways to accomplish this, though.
Mentors
- Abhilash Raj (maxking on IRC)
- Stephen J. Turnbull (yaseppochi on IRC)
Developers' Documentation for Hyperkitty
Hyperkitty is GNU Mailman's official archiver. However, it also supports some advanced functionality which allows users to send messages/emails through its web interface.
HyperKitty was developed with support from Red Hat. As the application matured and the company's needs changed, the original developers were reassigned. Documentation at the function level (docstrings and comments) is pretty good. However, documentation of the configuration and architecture of the application is almost nonexistent, and would be very helpful in onboarding developers who want to work on this subproject.
Additional Requirements
- Intermediate level Python programming
Mentors
- Abhilash Raj (maxking on IRC)
- Stephen J. Turnbull (yaseppochi on IRC)
Developers' Documentation for Postorius
Postorius is GNU Mailman's bundled "dashboard" for mailing list administrators and subscribers.
The main developers of Postorius have become less attached to the project. The documentation has become out of date over time. Improved documentation of the configuration and architecture of the application would be very helpful in onboarding developers who want to work on this subproject.
Additional Requirements
- Intermediate level Python programming
Mentors
- Abhilash Raj (maxking on IRC)
- Stephen J. Turnbull (yaseppochi on IRC)
FAQ
This FAQ is a placeholder ripped off from our GSoC page. Check back later to see if it's more useful for tech writers!
- I am interested to contribute to Mailman and participate in GSOC, how do I start?
This page might be of some help.
This question has been asked tons of times on the mailing list (mentioned above) and IRC Channel (again, mentioned above). Both of them are logged publicly and are searchable. It would be really nice to go through them once before you ask the same question again. More specific questions are encouraged and receive more attention than "How do I start?". Mentors do try hard to reply to each and every email to the developers list, but in case you don't get any replies on trivial questions, don't be discouraged. Also, in case you are a student, helping others with small problems that you know about is also a great way to get noticed. Don't worry too much about giving wrong answers, list is constantly monitored by the core developers and your mistakes would be corrected.
- I am a beginner, what is the best way for me to contribute?
Issues, bugs and tests are obviously a good way to contribute. But, writing/improving documentation is another great way to contribute for beginners. It doesn't have to be a real commit or patch, write up a detailed blog post about what problems you faced while setting up mailman for development. What parts of mailman you find are difficult to understand? What are awesome things about mailman?
Note: To qualify for Google Summer of Code, your proposed project must be a coding project. That's Google's rule. Documentation and tests help to make a substantial contribution, but only count toward GSoC to the extent that they apply to your new or changed code. Additional work on documentation or testing is considered a community contribution, which is a consideration in deciding who to accept.
- My MR has been pending for a long time, what should I do?
In most of the cases the reason for a MR to be pending is that there is either something missing or something incorrect. In either of those cases, first check the MR itself and any issues associated with it, to see if there are comment you have missed. If it's not obvious what you need to do next, contact any mentor or the org admin (maxking) and we'll look into it, or ask the relevant person. I don't mean that you do that for each one, just the ones that haven't been noticed by anyone for a *long time*. (Use your judgment as to what is "long" when there's a deadline coming up.)
Documentation & Installation
This section is probably not useful to technical writers. But just in case your hobby is programming, we've borrowed this from our GSoC page, too.
Here are some useful links to get you started with Mailman Development:
Mailman is written in Python. Mailman supports Python 3.5+. Each individual projects may have their own restrictions on the Python versions you can use depending on the support of the their dependencies.