All I wanted to do was to add a mention of Github changeset links to the MacPorts documentation.

I like contributing to free software projects. One way I pick which specific contribution to make, is that I recall something which was an obstacle for me. I come up with a change which would reduce that obstacle. I look through the project’s open source for how to make that change. Then I make a pull request, or submit a patch, which contains that change.

Sometimes, in order to make the change, I need to learn the tools or languages which that project uses for its code or documentation. That can lead to a cascade of subsidiary tasks or related changes. This is a story of that happening to a ridiculous degree, about 20 months ago.

I am a big fan of, and longtime user of, the MacPorts project. MacPorts brings a huge amount of free software to the Macintosh platform, by automating the building of that software. An important part of MacPorts is that it collects the dependencies, the other free software on which a particular piece of software depends to build and run.

It is routine to run into bugs in the software MacPorts delivers. So it is routine for diligent users to file bug reports against that software. This lets other MacPorts contributors know about the problem. Often someone will volunteer to fix it. And in a bug report, it is useful to be able to link to a particular revision of the MacPorts description of the software. This is known as a “changeset link”.

So, here was my situation. I was using MacPorts. I filed a bug report, known in MacPorts as a “Trac ticket”. I linked to a changeset in the MacPorts software repository on GitHub in a clumsy, incorrect way. A MacPorts leader kindly pointed out my mistake, and changed the link to be a correct changeset link. I read the instructions for writing Trac tickets. There was no mention there of the correct format for links to GitHub changesets.

OK, I thought. I’ll write a simple change to those instructions, adding a couple of sentences on writing GitHub changeset links correctly. How hard could that be?

Goal 1: determine what documentation change would be sufficient. This was simple. The instructions mentioned formatting briefly, and linked to a MacPorts wiki page on WikiFormatting. That page in turn broke out detail about links to another wiki page TracLinks. So, a good change would be to add, to page WikiFormatting, one line to a five-line table entry on TracLinks; and to add, to page TracLinks, one entry about changeset links to an overview table, and a new section about “Links to MacPorts on GitHub”.

Subgoal 2: Find out the project’s culture around changes like this. Most projects with wikis encourage people to “be bold” and make changes. The whole idea of a wiki is to encourage the community to make small changes easily. The value of a wiki to a project like MacPorts is so that ordinary users like me can make small documentation improvements like this. Still, different projects have different cultures around different kinds of changes.

I posted a message to the MacPorts-users email list, asking if this change would be welcome. I received an encouraging reply from a leader of the project. Wiki contributions are welcome. However, those two pages of the wiki are instructions by the makers of the wiki software itself, about how to use the wiki. It might be inadvisable to change them.

Subgoal 3: figure out if changes to the wiki pages WikiFormatting and TracLinks was inadvisable. I found and studied the Trac wiki administration guide. There was a section on upgrading Trac’s documentation. Sure enough, it implied that those pages would get overwritten by upgrades to the Trac software. A look at the edit histories for those pages confirmed this.

Subgoal 4. Figure out the right way to structure wiki pages so that changes can survive documentation updates. I had the idea to add a new wiki page, to list our non-standard changes to the Trac Guide. It would list my changes to WikiFormatting and TracLinks at first.

Subgoal 5. Add a new wiki page, TracGuideLocalChanges. Oh, I was not permitted to add pages. MacPorts had set up their instance of Trac with this limitation.

So, subgoals 5 and 4 failed. Where else could I document changeset links? The main MacPorts Guide was a web page. I could perhaps suggest a change to that. But I could still make my changes to the wiki pages.

Subgoal 6. Make my edits to wiki pages WikiFormatting and TracLinks. This went smoothly. Editing Trac pages was easy. And it was not a waste of time. The edited pages have provided better guidance about GitHub changeset links for 19 months and counting.

Subgoal 7. Figure out a place in the MacPorts Guide to describe GitHub changeset links. Simple. In the Trac Ticket Guidelines section of the Guide, I could add one sentence to the TL; DR for the “Description” field. Below that, I could break one sentence about formatting into a separate paragraph, with four additional sentences to describe changeset links and give examples. This would be a small, reasonable change.

Now, I needed to find out where the sources for the Guide were, and how to change them.

Subgoal 8: Read instructions on changing the MacPorts Guide. This looked easy. The Guide itself had a section, Updating the Guide. How hard could this be? Step one, check out a copy of the repository with the Guide sources.

Subgoal 9. Make a local copy of the Guide sources. Identify the repository with the MacPorts Guide sources, which is in GitHub. Start up my code editor. Clone the macports-guide repo from GitHub to a local copy.

Subgoal 10. Attempt to build the existing documentation in my local repository. This is the usual way to lay a foundation on which to construct my changes. But the build failed.

Subgoal 11. Fix the problem which causes my build of the existing documentation to fail. I discovered that the MacPorts Guide section, on setting up to edit the MacPorts Guide, was out of date. I found the Readme file within the Guide repository. It gave the correct information. It was a simple correction to my local repository, and I could build the existing Guide.

Subgoal 12. Figure out how to apply improvement from Subgoal 7 to the source files for the MacPorts guide. These source files are in DocBook format.

Subgoal 13: Learn enough about DocBook to stumble my way through my changes.

While making the edits, I discovered that the MacPorts Guide section on actually editing the MacPorts Guide and submitting changes is incomplete.

Subgoal 14: Figure out how actually to edit the Guide and submit changes. Work out the parts missing parts from the Guide on editing the Guide.

Subgoal 15. Make the simple fix to the MacPort Guide about setting up to edit the Guide. My original goal was to add missing information to the MacPorts Guide about changeset links to GitHub. But the solution to Subgoal 11 was also useful. I made a branch to my local repository with a simple correction to the Guide. I packaged it as a Pull Request (PR) 38, and submitted it.

Another MacPorts contributor reviewed my PR 38. They asked that I make a parallel change to an alternate form of the same documentation: the AsciiDoc version.

Subgoal 16. Learn about how the AsciiDoc version of the MacPorts Guide sources work. They use the AsciiDoc format and AsciiDoctor tool.

Subgoal 17. Learn enough about AsciiDoc format and AsciiDoctor tool to stumble my way through my changes. I installed the AsciiDoctor tool via MacPorts. I built the AsciiDoc version of the existing Guide.

Subgoal 18. Address the comment from Pull Request 38. This was to apply my simple fix about setting up to edit the guide, also to the AsciiDoc version of the MacPorts Guide. It was a simple edit, similar to Subgoal 15, but in the other format. I updated PR 38.

Submitting PR 38 was evidence that I had achieved Subgoal 14. I had figured out how actually to edit the Guide and submit changes.

Subgoal 19. Improve the MacPorts Guide instructions on how to improve the MacPorts Guide. This required writing a couple of pages of new text. I carefully worked though the process, so that I could document each step.I made a new branch of the MacPorts Guide repository for this edit. I painstakingly wrote the new content. I discovered that there were kinds of content (e.g. command listings) for which I did not yet know the Docbook syntax.

Subgoal 20. Learn more about the DocBook format in order to figure out how to format all the different kinds of content I want to include.

Subgoal 21. Make an AsciiDoc alternate format of the Docbook changes from Subgoal 19. I tried, but it turned out to be too difficult. Specifically, I could not see how to represent in AsciiDoc certain kinds of content (e.g. command listings). So instead, I filed a MacPorts ticket as a reminder to people in the future that this worked needed doing.

Subgoal 22. Raise the question of whether it is worth continuing with AsciiDoc format. I decided that I was not convinced that AsciiDoc was a better format for MacPorts than DocBook. But I was convinced that maintaining two separate formats of the same source documentation was a burden.

Subgoal 23. Submit the Docbook version of my changes to the MacPorts project. I submitted Pull Request (PR) 39.

By this point, I had learned how to make changes to the documentation, I knew how the real process differed from the documented process, and I had proposed documentation changes to match the real process. I was finally ready to make the original contribution which motivated this whole cascade.

Subgoal 24. Actually apply improvement from Subgoal 7 to the source files for the MacPorts guide. Subgoal 12 was my effort to learn how. This subgoal was applying that learning. I made a new branch of the macports-guide repo to describe GitHub changeset links. I authored my modified text. By this time, I knew the enough Docbook syntax to cover the content.

Subgoal 25. Make the equivalent AsciiDoc source for the GitHub changeset links. Copying over the text from the DocBook format was no problem. Applying the AsciiDoc format was more difficult. Because I had punted on Subgoal 21, I had to learn some new AsciiDoc format — though not all of what I would need to learn for Subgoal 21.

Subgoal 26. Learn enough new AsciiDoc to format the text about changeset links.

Subgoal 27. Submit the Docbook and AsciiDoc versions of my GitHub changeset links description to the MacPorts project. I submitted Pull Request (PR) 41.

Subgoal 28. Notify the project, and encourage acceptance of my submissions. It is typical for open source projects to allow only a few trusted participants to commit changes to the project’s source code. Regular participants like me may propose changes, but the trusted ones must review and decide whether to accept. That is a demand on their time, and it does not always happen quickly. So I sent a message to the MacPorts users email list. I discussed what I did, primarily to the wiki pages, and whether that’s the right thing.

The work is not done until the changes are committed to the project’s source code, and the resulting documentation is updated for everyone. That has still not happened, 20-some months later. I have further goals on my list for the future:

Subgoal 29. Get acceptance of my 3 Pull Requests. The next step is to encourage those with the authority to review them.

Subgoal 30. Get a project decision about how to handle the AsciiDoc version of the guide. The next step is to encourage discussion about whether to continue with the AsciiDoc version of the Guide, and how to get away from the present situation of needing to make two parallel copies of the documentation source files.

Subgoal 31: If discussion starts about my Wiki page changes, participate; and hopefully preserve those changes. At least for the Wiki, I have the advantage that my changes stay until someone else removes them, or the MacPorts installation of Trac is upgraded.

Subgoal 32: Identify and remove obstacles to improving MacPorts documentation. I proposed some improved content to the existing documentation. That would have made achieving many of my subgoals easier. However, the long inaction about reviewing and accepting my submissions is not a problem of documentation. The project could identify that other obstacles, and work to remove them. I could choose to encourage that discussion.

So there you have it: a desire to make a simple change to the project’s documentation cascaded into a further 31 subgoals, and many hours of work. So far. And that was just my tasks.

By the way, I do not write this to criticise the MacPorts project. In fact, I love it. The software which the project delivers is very valuable to me. The people participating in the project, particularly the leaders, are very welcoming and friendly. The tools and workflow are generally good. (Well, there is room to improve the documentation workflow.) They are a pleasure to work with.

I write this to show (even to myself) exactly how an apparently simple change can cascade into a lot of work — even with a motivated contributor, friendly people, and good workflow.

2 Comments »