On mentoring for an an open-source internship

#wagtail #beginners #opensource #programming

This year I was able to take part in an open-source internship run alongside Google Summer of Code but sponsored by Torchbox. This internship allowed one new to open-source developer to submit a project proposal and then work alongside myself and others to build something core into Wagtail. Wagtail is an open-source CMS built on Django.

It was a really big few months for me - while I was given paid time (4 hours) a week from my work, Virgin Australia, the time taken each week was much more. Especially when we had to consider multiple time zones across the team (UK, India, Australia). It was an incredibly rewarding experience though and taught me a lot about what it is like to help new developers get up to speed and when to push but also when to help with a bit of the solution.

It is easy to forget what it is like to write code or learn a framework for the first time, not just the first time in a new language but the first time completely.

While I have only been a full-time software developer for about five years, I have done programming in some form for many years before that.

At a previous job, not as a software developer, myself and a few others endeavoured to build a CRM for the church I worked at. We opted for web2py simply because it was the thing I had first learned after learning Python and had found incredible power in building something that people could use.

Learning this new framework meant learning so many things at once, and also intentionally or probably more so out of blissful ignorance, not learning some things. I never really picked up git until much later and was enamoured by the browser IDE that web2py shipped with, as it meant I did not have to think about that big unknown. To no one’s surprise, this caused many problems with writing directly to a production server without any version control history to fall back on.

These last few months I was able to get a somewhat fresh perspective on what it is like for all of us learn something new that is incredibly complex. You cannot possibly learn it all at once, nor can you really understand where to start learning and what bits matter now or matter later. It has reminded me of the importance of small goals and being ok with splitting those goals up even further until you can get some momentum.

I have had the pleasure over this time to be a mentor of Google Summer of Code (GSoC), technically Torchbox’s internship that ran alongside other GSoC projects for the Wagtail community. My employer, Virgin Australia, generously approved a set time each week for me to be a mentor and help a new developer get up to speed and contribute solidly to Wagtail (an open-source CMS built on Django).

During this project, I have been absolutely inspired by the tenacity and grit of Paarth who has gone from contributing small CSS / documentation fixes to building out full Django template components used across the entire CMS in a matter of weeks. Paarth was the student I got to mentor, he is in his third year of studies in one of the top tech universities in India. He worked incredibly hard even to get approved as a contributor, preparing a full project proposal from a reasonably ambiguous goal. That goal was to Unify the UX across large parts of Wagtail, originally we just called this ‘Apply page editor UX to other parts of Wagtail’ which did not do the enormity of the task justice. Paarth contributed close to 20 pull requests even before the project started, he advised me that he would keep his phone on loud notifications for only Github to keep on top of any new ‘good first issues’ that arose.

As we, Thibaud and Helen, got to know Paarth through the project I am glad to say that we created a bond and it was great for me to hear about his university life. I learned that Paarth had spent the first two years of his course remotely (due to the pandemic), and also how much harder he has had to work to get into uni and get into the course he wanted (well, almost, a course that is close to what he wanted). How far he lives from uni, an overnight train ride just to visit his family, along with many other things that have been hard for him but I had taken for granted as easy during my university days.

All of this alerted me to the fact that I have had it relatively easy here in Australia with my university life (a long time ago) and career. I have had to work hard but I have not had to fight or push in the same way Paarth has. In all of this I am thankful for the opportunities that have come my way but incredibly encouraged that there are legends out there like Paarth getting started while also wanting to be involved with open-source.

As for the project itself, it was an incredible success, with large parts of the Wagtail UI brought up to scratch with the new layouts, designs and cleaner HTML/CSS to manage. There were a lot of bug fixes, some existing and some introduced, along the way with a solid amount of unit tests added to support them. I was able to lean on the incredible advice of Helen and Thibaud from Torchbox in the UK, including when I sneaked off for a trip to Bali (yay) with my family. This helped me get different perspectives on how to approach problems and how to work in a large, long-lived codebase.

Core skills

Some of the things I was able to help guide.

Git - Despite my late learning of the power of git, this is something that came up again and again in our project. Botched rebases, switching branches, code conflicts, adding messages to commits and when a Git GUI is helpful.
Linting - Wagtail has multiple layers of code checks and linting, including Python/JavaScript, HTML linting, being able to understand these errors, setting up your editor, running the formatter are all critical to faster development.
Reading the issue - This is something we spent time on a lot, reading the issue raised (a bug or enhancement), learning to read it twice, asking questions and clarification, and the inevitable de-sope of things to future issues.
Reproducibility of the issue or problem - When solving bugs, it was important to make sure that he could reproduce the issue and truly understand it, before going in to solve it.
Unit tests - Writing, debugging, and refactoring unit tests is a whole universe of complexity but it is something that helps to ensure that improvements to the code can last longer and be more reliable for future development.
Reading a file & writing field notes - We spent a bit of time walking through existing code, just reading it line by line and writing notes. One thing that helped was to encourage the idea of ‘field notes’, just summarising the file in your own words and also breaking it up into bullet points to help understand it.
Make small changes and get early feedback - Instead of solving the whole thing at once, solve a small part of it and get feedback.

Bonus learnings

Some things I learned for me along the way, even if it means a bit more empathy for others getting started.

SCSS/CSS is hard - I often see Twitter threads about CSS being easy/hard or not a ‘real’ language. It is incredibly complex and requires a lot of patience and understanding to build things well that work across the myriad of breakpoints and browsers.
Long-lived code is a minefield of complexity - It is very easy to change things in one place and it breaks another place. This is something to not just know on the surface but really understand, it is especially complex for code that is used/extended by others like Wagtail.
open-source code needs to consider maintainers - While the above may not be too different to any other large project. The key difference with a large open-source project is that there are a wider range of contributors with a wider range of skills to consider and also conflicting PRs and work is almost guaranteed when doing anything large.
time zones add friction - I love remote work and even travelled for a year while working for companies back in Australia. However, when there are three time zones to consider (India, UK, AU) and working hours, uni classes and people with families it becomes very much a juggling act to line things up.
Zoom has incredibly good noise cancellation - I tried many others and Zoom is the best, I want Google Hangouts (or whatever it is called now) to be great but nothing matched Zoom. Maybe Google should stop building new chat / call apps.
Planning & Deadlines - Planning in sprints helped break up the work into blocks but in reality it did not follow that at all. Over the project, we found better things are 'themes' or 'blocks' of work in similar areas of code or similar goals with check-ins on those blocks every two weeks.
Accessibility first - Building things well with accessibility baked in solves for a lot of problems later, you have a better DOM structure and more thought-out code to work with.
Fast & slow - Some things are faster than you expect, some things are slower, often by orders of magnitude, your estimates will only be correct when the work is done.

What was achieved

I will not steal the thunder from Paarth, but just call out some of the most exciting features and some stats from the project.

Globally - Wagtail has an incredibly fresh UI, that feels much more consistent across parts of the code and is substantially more accessible and usable with other languages.
Two very old pull requests, from 2019 & 2020, were rebased with fixes and merged in.
Was able to close one of the oldest bugs in the project, from 2016.
Paarth moving from no contributions to the 21st most contributions - https://github.com/wagtail/wagtail/graphs/contributors.
Authentication pages, we thought they would be out of scope originally but Paarth was able to get them done and they look so much better.
Less yelling - the first pull request from Paarth, even before being accepted, was to remove all the uppercase styling on buttons/menus - thanks for reducing the yelling in Wagtail. https://github.com/wagtail/wagtail/issues/7624
You can read Paarth's blog post about his open-source internship experience.

Acknowledgements

It would be remiss of me to not call out those involved throughout this project.

Paarth - Congrats on putting yourself out there and working incredibly hard every step of the way, even while going to uni in person for the first time and being away from your family.
Thibaud - Thanks for joining so many of the calls, even when you were busy or about to go on leave. Thanks for always pushing back when needed on solutions that were a bit too overkill while also pushing the UI forward to be better for everyone.
Helen - It was great to get to know you and thanks for the great guidance on our calls on how to work with various generations of CSS and classes.
Virgin Australia - Thanks Ken & Annette, I was unsure what you would say to me asking for 4 hours a week for many months to do this and I really appreciate the trust you have for me to make this work.
Torchbox - Thanks for sponsoring Paarth, even though we did not get all the GSoC slots and thanks for all the resources you put into the Wagtail community generally.
Wagtail community - So many PRs had reviews from other core devs and along the way, there was even work in the UX Unification scope that got randomly contributed by others meaning we could do other things.
Bec & Leo - My wife and son, you made it possible for me to do the late night & early morning calls and have been so supportive of my desire to help with open-source over the last many years.

Round two?

In hindsight it would have been better to have a clearer goal, the project was a bit ambiguous which gave us room to move but felt like some things were not really solid enough to get good momentum on. I do feel that Paarth was an incredible contributor and took on the challenge well, pushing through, and was happy to give things a go a few different ways to see what worked the best.

This was an incredible opportunity to help make Wagtail better, help grow my skills and also get to know some great people, so yeah I would do it again!