The past month has flown by so quickly. After a full month dedicated to contributing to the open source community, I want to reflect on my experiences with Hacktoberfest 2018 and write a bit about things I learned over the past month, what went well, what I would do differently next time, and a general reflection on the Hacktoberfest event itself.

First, a reflection on my goals. For the month of Hacktoberfest I wanted to make contributions to a number of different projects, and I specifically wanted to contribute to at least two projects that use Rust. How did I do?

In the past month, I made 4 contributions (issues or pull requests) to 2 different projects that use Rust. Ironically, I did not have the opportunity to use Rust or write any code as part of those contributions as all of those contributions were in the form of documentation. However, I did still achieve the goal I had set for myself for Hacktoberfest!

I also ran some quick stats on my blog posts for this past month, as shown below:

wc -w content/posts/2018/hacktoberfest-week-*.rst
     673 content/posts/2018/hacktoberfest-week-one.rst
     822 content/posts/2018/hacktoberfest-week-two.rst
    1579 content/posts/2018/hacktoberfest-week-three.rst
     514 content/posts/2018/hacktoberfest-week-four.rst
     425 content/posts/2018/hacktoberfest-week-five.rst
    4013 total

For the month of October, I wrote a total of 4013 words about my contributions to open source, writing a one-time maximum of 1579 words during Week 3 about documentation and different ways to contribute to open source projects.

What Went Well

Overall, I think Hacktoberfest was a positive experience. I had some really great interactions with the open source community on GitHub, and all of the project maintainers were very encouraging and helpful. Special shout-out to Sendil Kumar N, a member of the rust-wasm team, for an especially warm welcome to the Rust and WebAssembly Book repository.

I am also happy to share that all of my pull requests were merged within the month. Hacktoberfest does not require pull requests to be merged as part of participating, only that they are created, but it was very validating that I did not have to go back to the drawing board or make many changes to my contributions for them to be accepted by the project maintainers. Hacktoberfest is definitely geared more towards small fixes and improvements, and while it is less likely to happen during an even like this I have made other contributions in the past that got tied up in bikeshedding and nitpicking such that no progress was made for weeks or months at a time.

What to do Differently

Now that Hacktoberfest is over, I definitely think it was a mistake to jump around from project to project. Every time I went to make a contribution to a new project I would have to ramp up again, learning how the project is organized, where I can find existing documentation, how to successfully contribute to the project, etc. I also didn’t feel like I was immersing myself in a community the way I had hoped to while participating in Hacktoberfest this year. As I have written about before, I am not a stranger to open source, so I definitely felt there was something missing this month, and I think the project-hopping contributed to this feeling.

The next time I participate in Hacktoberfest, I will be trying to focus a lot more on contributing code rather than documentation or other forms of contribution. I wrote at length about different forms open source contributions can take during week three of Hacktoberfest and while I do not want to deemphasize the importance of things like documentation I am a programmer at heart, I genuinely enjoy writing code, and I’d like to do more of that.

Reflecting on Hacktoberfest

Hacktoberfest is a great outreach event to get more people participating in open source. There is definitely more awareness in the community the past few years about the new contributor experience, and GitHub tags like “help wanted” and “hacktoberfest” make it a lot easier for people to find projects and get involved. One of the downsides to this is sifting through all of the results to find a project of interest or an issue that details a fix or feature a new contributor might actually be able to tackle.

Which brings us to: time constraints. Hacktoberfest is a month-long event, which seems like an excessive amount of time on October 1st, but once the event moves into its last week everyone realizes how little time a month turns out to be. The Hacktoberfest global stats bear this out: there was a pretty healthy uptick in contributions during the last few days of the event as more contributors worked towards completing their five pull requests.

These time constraints can also make people feel like they need to contribute as much as possible as quickly as possible, leading to contributions that focus on quantity over quality. Or interactions like the one I had on one of the first projects I was going to contribute to for Hacktoberfest: I indicated my interest in attempting to fix an issue, and someone else - who did not participate in the discussion on the issue or check if an issue had already been claimed - submitted a pull request ahead of me. Twice. Thankfully I had not started on an implementation at that point, so I simply moved on to another project and a different contribution.

Part of the solution to this problem definitely falls to project maintainers. Creating separate issues for each contribution and assigning those issues to the claimant can resolve the ambiguity of who has priority to submit a pull request for a given issue. Also, not merging pull requests from anyone other than the claimant would go a long way to encouraging potential contributors to get involved and make sure they are taking unclaimed issues, rather than dropping off a pull request and moving on to the next contribution.

In the projects I did contribute to, I had a really pleasant experience. The Rust projects in particular are very welcoming; the Rust community is well known for being friendly and inclusive and it was a pleasure to contribute to making these projects even better.

All in all, I learned a lot this Hacktoberfest, particularly about myself, the kinds of projects I’m interested in, and how I personally like to contribute to open source. I’m looking forward to putting those lessons into practice during next year’s Hacktoberfest, as well as in the rest of my open source contributions going forward.

With this fifth week, Hacktoberfest 2018 comes to a close. I’ll be doing a retrospective on the whole month of contributions soon, but that is not this post. This week, I was able to make one of the contributions I had started back in week three, a documentation contribution to the Rust and WebAssembly Book.

As I mentioned in that post, I had filed rustwasm/book#127 to suggest some improvements to the explanation of src/utils.rs, a module that the rust-wasm project template provides to make working with Rust compiled to WebAssembly easier including some debugging helpers in the form of a panic hook to print well-formatted and helpful wasm error messages to console.error. Nick Fitzgerald, a member of the Rust dev tools team, responded to my issue and said that he would be happy to merge a pull request that did the rephrasing I had suggested. Since I had already done the work up-front when I filed my issue, I was able to get a pull request with the change up very quickly and it got merged the same day.

My change is live on the Rust and WebAssembly site right now, and it feels really great to see something that I wrote included in a project in which I’m excited to get even more involved. Big thanks to Nick for getting back to me about my proposed change and for the quick merge on rustwasm/book#129 to get it incorporated.

With that pull request opened (and merged), I was able to achieve my five pull requests for Hacktoberfest and secure my limited edition T-shirt. The T-shirt is nice, of course, but the real benefit of Hacktoberfest is to all the open source projects that took pull requests this past month, as well as for all the participants who were able to level up their programming skills while contributing to the open source community. More on that in the next post where I’ll summarize my experience participating in Hacktoberfest 2018 and talk about what I learned, what went well, what I would do differently next time, and a general reflection on Hacktoberfest itself.

Hacktoberfest week four! In keeping with the theme I set last week I continued to improve open source project documentation as part of Hacktoberfest. This week I returned to dplesca/purehugo, the theme I use for this blog, to help out with improving some areas of the documentation I noticed could use a bit of polish during my first contribution to the project during Hacktoberfest week two.

In dplesca/purehugo#28 I rephrased the section of the README.md that deals with code syntax highlighting on generated blogs. As I mention in the issue, it seems as though the original author simply missed a word when writing the section:

All you need to do is to let rainbow.js the language of the highlighted code […]

which should instead read:

All you need to do is to let rainbow.js know the language of the highlighted code […]

The simple fix in this case would be to add the missing word. However, since I knew I would be editing this part of the document anyways, I decided to take a bit more time and rephrase the existing wording to simplify the instructions and use more specific language to instruct new users what they need to do to get the highlighting library to pick up the desired language. I also added a full example of how to apply Go syntax to a code block using Markdown, as I find seeing complete code samples or full examples in documentation to be very helpful when I’m learning a new tool or framework, and serve as quick reminders if I’m returning to a tool or framework I haven’t used recently to get me back on track.

This week turned into a twofer because while I was working on dplesca/purehugo#28 I noticed a small spelling error elsewhere in the README.md file and submitted dplesca/purehugo#27 to correct a word in one of the document headings. I only noticed the spelling mistake as I had just set up proper spell checking in Visual Studio Code using Spell Right by Bartosz Antosik to warn me about typos and other spelling errors. I had been under the impression that VS Code shipped with spell checking by default but this does not seem to be the case. Further, the VS Code spellchecking addon I found published by Microsoft is marked as deprecated and suggests finding an alternate addon. Correcting minor typos in documentation is small potatoes compared to some other Hacktoberfest contributions, but they are important changes that affect readability, comprehension, and the flow of the document(s) in which they occur.

The end of Hacktoberfest is almost upon us, and I have one last post to share about my final contribution this month. Look forward to a piece about my first major contribution to a Rust project!

As of last week we are just about half way through Hacktoberfest. Time is just flying by, and I can’t believe how quickly it’s passing. In my previous Hacktoberfest post I wrote about my slightly self-interested contribution to dplesca/purehugo, the theme I use for this blog, and how I used some of Hugo’s built-in functions to normalize URLs that used the .Site.BaseURL variable.

My contribution this week for Hacktoberfest is minor, but it started me on a path to encounter a number of issues with a common theme that should leave me with plenty of work to do over the next few weeks and possibly past the end of the month.

Theme Week: Documentation

There has been a trend over the last number of years for contributors to open source to diversify how they contribute to open source. Code is not the only kind of contribution maintainers hope to receive, and they are happy to receive contributions in the form of documentation, code examples, sample projects, and feedback from first-time users, among others.

For Hacktoberfest week three, I focused my efforts on project documentation, or a lack thereof, specifically from the perspective of a new user. So far during Hacktoberfest I haven’t made more than one contribution to the same project; instead I’ve jumped around quite a bit to different projects that use many different languages and project structures. This project hopping has given me some perspective on the onboarding and getting started instructions of a number of projects, which are critical for encouraging adoption and helping new users get up to speed on how to use or contribute to a project, application, or service. Documentation can also be tricky to get right the first, second, or even fifth time because it is hard to write a document that is useful for every audience, especially if the topic is technical in nature and the author(s) can’t make many assumptions about the audience’s technical background or ability. Many projects deal with this by dividing the documentation in two: one set of high-level documentation on getting the project up and running aimed at users, and another set of documentation that augments and extends this high-level documentation aimed at contributors and developers that provides much more technical detail.

This past week also reiterates the importance of contributing to projects in ways other than implementing new features, writing test cases, or fixing bugs in code. There are so many ways to contribute to open source projects, and one of the best ways new contributors can help a project is to verify the project’s onboarding flow by following basic steps like the project setup information and getting their development environment up and running. These are tasks that established contributors and maintainers do not have to do very often and documentation can get out of date; new contributors are great at spotting problem areas in guides, tutorials, and example code that can improve the onboarding experience and identify areas where further explanation may be necessary that established contributors may not be able to see.

Project One: rust-wasm

I have been excited about WebAssembly since I first heard about the work being done to support it in multiple browser engines. WebAssembly is a binary instruction format predominantly designed for the web (though its success on the web will surely spur adoption in other areas just as NodeJS forced us to rethink possible applications for JavaScript) that can be targeted by many other languages like C++, Rust, Go, and Java, among others. rust-wasm is the Rust initiative to provide compilation for the wasm target as well as support interoperation with existing JavaScript code both shipped in browsers and provided as libraries through tools like npm.

I wanted to get up and running with WebAssembly as a compilation target for Rust, so I decided to read some of the core documentation provided by the rust-wasm team: the Rust and WebAssembly Book. After taking a brief detour to set up a personal Homebrew tap for the wasm-pack tool (which I hope, once the prerequisite Rust version lands on the stable channel, I will be able to contribute back to homebrew/hombrew-core and rust-wasm), I was able to set up all of the necessary project dependencies to start working through the tutorial.

Hello, World!

The Rust and WebAssembly Book bases the tutorial off a project template to get new users up and running more quickly. It spends a portion of the introductory section talking about each file in the template and its purpose in the larger project. When I got to the section describing wasm-game-of-life/src/utils.rs, I was given this explanation:

The src/utils.rs module provides a couple included batteries that we will use later in the tutorial. We can ignore it for now.

— Rust and WebAssembly, 5.2 - Hello, World!

After the reasonably detailed explanations of other files in the project, this section stood out to me as one that could be improved. This section also makes reference to a philosophy of “batteries included”, which I had only ever been exposed to before in Python jargon and that may not be familiar to everyone who has not had a similar exposure, or for whom English is not their primary language and the idiom is lost in translation.

Being a fresh set of eyes on the Rust and WebAssembly Book, I filed rustwasm/book#127 to discuss some suggestions for how this section could be improved without the need for jargon-heavy idioms and to provide more details about the particular module in question. At the time of publishing I have not heard back from anyone on the rust-wasm team, but I am hopeful that I will be able to submit a pull request before the end of the month to improve this part of the tutorial.

Typos and Transcription Errors

Reading through the rest of the page, I ran across the simple error of a duplicated word in the explanation of wasm-game-of-life/www/index.js. I submitted my correction as rustwasm/book#128 and it was accepted the same day. I even received a congratulatory message from one of the maintainers on my first contribution to the project which, as my first interaction with any of the project maintainers, is a nice personal touch that definitely makes me want to to continue to contribute to rust-wasm.

Project Two: Diesel

I have been playing around with reimplementing a currently active Postgresql-backed project using Rust, and discovered Diesel as one of the ORM tools at the forefront of Rust development stacks. As with rust-wasm, I have not used Diesel in any of my projects, so I turned to the getting started guide Diesel provides. It wasn’t long after I got the diesel-cli tool installed that I ran into a discrepancy between the guide and the behaviour of the CLI tool, so I filed diesel-rs/diesel#1891 to detail my expectations along with the actual output the tool was producing, as well as some suggestions for improving the clarity of documentation in a few disparate but related areas of the codebase and guide.

I am of course very grateful for the guide because it is much more approachable - with many code samples and examples - than reading highly technical API documentation or man pages. However, it can be intimidating for a new user if they are following along with the steps in the guide and something unexpected happens; often the new user doesn’t know if they did something in the wrong order or missed an important step, or if the guide is simply out of date and they are not sure how to get around the outdated part to continue their progress. It is also common for code and documentation to get out of sync, resulting in confused and annoyed users. Unfortunately there isn’t a great technical solution to this issue and authors need to always take care to not only update code but also documentation, though Rust’s documentation tests are one example of a tool that can help by ensuring that example code included in comments is up to date and working.

Project: Next

As I am still a new user of rust-wasm and Diesel, I am sure there are still many things I can contribute to these projects, both in terms of improving the onboarding experience for new users as well as other non-code contributions. I also have my eye on a few areas of the guide for Rocket, a web framework written in Rust that was the reason I started using Diesel. I’m hoping to hear back soon about the two issues I filed to improve documentation, and I’d like to take the time this month to shepherd them through to getting pull requests opened and merged. As for this week, I’ll be picking out my next few contributions for Hacktoberfest and might also start thinking about picking a project to stick with for a while now that I’ve worked on a number of projects so far this term.

Hacktoberfest week two! Week one was all about getting into the groove of Hacktoberfest, making a small change to contribute, and finding out about other awesome projects in open source and my area of interest.

My contribution for this week had a bit more self-interest involved; I contributed a change to dplesca/purehugo, the Hugo blog theme I use for this blog, to normalize URLs that use Hugo’s .Site.BaseURL variable.

The Problem

Using the dplesca/purehugo theme, I was noticing that many links to other parts of the site - that is, links that were not external links to e.g. GitHub or Twitter - contained multiple slashes after the site root. Modern web browsers are really good at dealing with partially-malformed URLs so there was no functional problem with any of the links as the browser’s URL parser took over and cleaned them up into a value it could resolve, but it would still be better if the URLs were correctly formatted when Hugo generates the static site content.

The malformed URLs looked something like this:

<a class="pure-button" href="http://localhost:1313//index.xml">[...]</a>
<a class="post-category post-category-open source" href="http://localhost:1313//categories/open-source">open source</a>

Delving into the template code revealed how dplesca/purehugo was generating the URLs:

<a class="pure-button" href="{{ .Site.BaseURL }}/index.xml">[...]</a>
<a class="post-category post-category-{{ . }}" href="{{ $baseUrl }}/categories/{{ . | urlize }}">{{ . }}</a>

The template string used .Site.BaseURL and appended a slash before the next URL fragment. Since this results in a double slash in the generated output, I presume but have not confirmed that .Site.BaseURL always ends in a trailing slash that needs to be taken into consideration when generating URLs relative the the site’s root.

The Solution

In a similar way to how we join file paths in NodeJS with path.join(), we almost never want to be responsible for building URL paths ourselves. Luckily, Hugo provides many built-in helper functions that cover a whole range of use cases, including the one I decided to use to normalize URL paths throughout dplesca/purehugo: absURL

From the Hugo documentation, absURL

Creates an absolute URL based on the configured baseURL.

where baseURL is the hostname (and path) to the root of the site which is set as part of Hugo’s site configuration.

This function was a perfect solution in most of the places where static files need to be linked and served to the client, such as JavaScript or CSS content. In those cases it was a simple matter of removing .Site.BaseURL and the subsequent concatenation and replace it with a call to the absURL function, like so:

<a class="pure-button" href='{{ "index.xml" | absURL }}'>[...]</a>

Normalizing the post category links turned out to be a bit more complicated than this simple substitution because these links needed to include more URL fragments to create the complete path. In order to correctly concatenate and then normalize these URLs, I turned to another of Hugo’s built-in functions: printf.

Hugo’s templating system is built almost entirely on top of Go’s built-in template package, which makes things very familiar if you have worked with Go templates before. It also means that Hugo can expose a lot of Go functions as Hugo functions available inside templates. In this case, Hugo’s printf function exposes Go’s fmt.Sprintf function which works much like printf in C.

This is the solution I came up with for building the more complicated post category link URLs while still being able to normalize the resulting URL using absURL:

<a class="post-category post-category-{{ . }}" href='{{ ( printf "categories/%s" . ) | absURL }}'>{{ . }}</a>

Unlike in NodeJS, in this case it’s safe to do a simple string concatenation of categories/<category-name> because unlike with file systems, the fragment separator in URLs is always the / character.

To be Continued

I am very thankful to purehugo’s author, @dplesca, for responding so quickly to my pull request with this change and for merging the pull request within a few hours of my submission. While working on this change I noticed a few other areas where I think dplesca/purehugo could be improved, and I’m looking forward to working on it more as I continue using it to generate my blog and host my site content.

Hacktoberfest continues on, and I need to start thinking about my next contribution. My school is on a break starting next week, so I’m hoping to find the time to dig into something a bit larger and more challenging based on the projects I’ve seen so far or had recommended to me by classmates.

Hacktoberfest, start! In my previous post I mentioned that I was hoping to find some interesting projects to contribute to this month, and so far I’ve come up with a pretty good shortlist of contributions I want to make.

To start the month off, I lent a hand to lk-geimfari/awesomo to reorganize their list of Rust projects. They had already reorganized the one for Python and suggested contributors use that as a model for the rest of the reorganizations. There are still a bunch of languages on the list in the tracking issue, so head on over and give them a hand!

The work itself was straight forward; contributors were asked to alphabetize the projects in the list, and provide a table of contents and headings based on the example. I think this was a great first issue for Hacktoberfest because my goal for this month is to contribute to at least two projects that use Rust, and what better way to find out about cool projects than working with a list chock full of them?

Alacritty

Alacritty was one of the first projects to catch my eye, not just because it was originally at the top of the list, but also because I saw an announcement post that Alacritty now supports terminal scrollback which introduced me to the existence of the project in the first place. Alacritty claims to be “the fastest terminal emulator in existence”, and uses the GPU for rendering to enable optimizations that aren’t possible using other terminal emulators. Alacritty is still very much in its infancy, with version 0.2.1 as the most recent release at the time of writing. Windows support is planned before a 1.0 release, so if this intrigues you and you’re a Windows developer have a look at the tracking issue and see if you can help out.

Diesel

Another project I was aware of before working with this awesome list of Rust projects is Diesel, a safe, extensible object-relational mapper (ORM) for Rust. When deciding on the technology stack for my capstone project this year, I investigated using the Rocket web framework written in Rust, and Diesel is one of the ORMs recommended in the getting started guide. Diesel provides a comfortable CLI experience for developers familiar with tools like ActiveRecord from Ruby on Rails and Sequelize in NodeJS, but drastically improves on both by leveraging Rust’s type safety and by “eliminat[ing] the possibility of incorrect database interactions at compile time.”

exa

exa is a modern replacement for the built-in unix ls command which aims to have better defaults and more features. I have been using exa myself for a few weeks and I am really enjoying the experience so far. With ls I set up a number of shell aliases and functions to do things like enable human-readable sizes and always show colours; in exa these features are turned on automatically without any setup. I am all for customizability in those cases where it’s absolutely necessary but sane defaults is almost always a better solution, especially with a tool that most of us use hundreds of times a day.

To be Continued

I definitely have some ideas about more projects that I’d like to contribute to after seeing the lk-geimfari/awesomo list, either this month for Hacktoberfest or on an ongoing basis. If Rust isn’t your language of choice, there are similar lists of projects in pretty much every popular language as well as some more obscure ones, so take a look, be inspired, and happy hacking!