A Djangonaut's First Ticket to Pull Request

Last week I created my first ticket using Django's Trac system.

Now, I have never used Trac before, and it has it's own wiki markup language (turns out Django uses a different markup language for it's docs, but we'll get to that later) with it's own special way to add a hyperlink,

Once I created the ticket, I was slightly overeager. I didn't realize that I had to wait for the ticket to be reviewed and accepted prior to being worked on. Fortunately, Django has great docs on how to claim a ticket if you didn't write one.

Working on the ticket.

At first, I couldn't find the instructions on viewing the Django documentation webpages locally, so I read the reStructuredText docs and utilized the Online reStructuredText editor to verify my changes to the docs.

I was lucky enough to get direction from Thibaud and fellow Djangonaut, Emme, about setting the documentation website up locally, and we realized that the Docs README.rst was out of date and we will be correcting it in the future.

Once I was able to run the Django documentation website locally and verify my changes, it was time to create a pull request. But wait! Actually I needed to squash a few extra commits. Django also wants you to rebase your branch, which turned out to be way simpler than I realized.

Like every repository, Django has its preferences. It says you can choose any name for the branch but it gives the example ticket_99999, I think this is a good precedent and should probably be followed; Django is written in Python and "explicit is better than implicit." The Django repository also prefers the commit message to be written in the past tense. There is a soft 72 character max, with a subject line separated by a space to be followed with lots of details (the more the merrier). By prefacing the branch name with "Fixed #123 -- Added..." Trac will automatically close the referenced ticket and post a comment to it with the full commit message. There are more details about how to modify your commit message depending on if the commit doesn't close the ticket or if you are working on a bug.

The Djangonaut Space Program turned this whole journey into a blast, making everything more enjoyable and efficient!