Some inspiration for your first pull request

I’ve worked with Umbraco for about seven years now but it took me almost three years to finally come around and submit my very first pull request. Heck, I even became an MVP 2016 without having done a single pull request to Umbraco (Don’t tell Niels..). So I know you think you got good reasons for putting it off: Lack of time, lack of experience and let’s not forget Mr. Impostor Syndrome.

It’s not that you maybe don’t know how to create a pull request, and maybe you have already read Sebastiaan Janssen’s amazing article about the proces of doing a pull request from the 2014 edition of 24 days In Umbraco. The problem is knowing what to do and perhaps you could use some inspiration.

What if I told you that by the end of this blogpost you will actually have submitted your very first pull request to Umbraco? Sounds too good to be true? Hear me out..

Start with something small

You probably already know about the GitHub issue tracker where you can go and check out reported issues or features and try to pick one that you think might suit you. However the smaller tasks have a tendency to be snatched quicker than you can say "Hello Unicorn!" and for a first-timer, taking on the bigger issues might feel a bit overwhelming.

Luckily there are a few smaller tasks perfect for anyone who just wants to dip their toe in contributing for the first time and try the water. These contributions are so small that they literally takes minutes to implement (you can fit one in on your lunch break), requires no experience at all (you don’t even need to be a developer) but still counts as an actual pull request and will earn you all the benefits and bragging rights of a GitHub contributor and I thought I would cover these for you today.

The Language files

If your native language (or any other language you’re fluent in) is not English then chances are the language files for your language are not as up-to-date as the English version. Anytime a new feature is added or improved in Umbraco, not all translations are added for every language in the world. Instead, if a translation is missing it automatically falls back to the default English translation until someone adds the correct translation and this is a perfect place for you to start looking for your first pull request.

The language files are XML files located in the Umbraco project and the en_us.xml is used as the default language. There’s probably some cool XML comparison tool you can use to compare the default file to your native language file, but the easiest way possible is just to spin up a fresh install of Umbraco locally (make sure you install the latest version) login to Umbraco and then switch your user's language to your native language. Now poke around and try to find any label or phrase that is either not correctly translated or in English. 

Once you’ve located a label, inspect that element in you browser and try to find something you can use as a reference (a class name or an ID usually works) to search in the Umbraco CMS project and once you find that element, you’ll see that it most likely has a <localize> element containing a key used to translate that specific element. Now find that key in your native language file or add it if it was missing together with the proper translation. Tada! You made your first contribution to the CMS project. Now see if you can find more missing translations to include in your first pull request.

The Documentation

The documentation section of our.umbraco.com is a great place to start if you want to contribute to Umbraco. Contributions to the documentation are also done using pull requests and will earn you a spot on the GitHub contributors list (more on this later) but you don’t even need to know how to use git, you can simply create a pull request directly from your browser. Each page on the documentation section comes with a button in the top right corner saying Edit this page which will take you to the correct page on GitHub for editing that page. It’s great, I’ve created numerous pull requests from the bus on my way to work.

If you’re confident enough to write a new section on a topic you feel is missing then by all means go ahead, but if you’re not really sure how you could contribute to the documentation then here are a few tips on where to start:

Grammar, spelling and typos

The documentation is English only, but not everyone who contributes to the documentation has English as their native language and this can sometimes result in spelling mistakes or incorrect use of grammar. Usually the Documentation Curators are really good at spotting these mistakes but sometimes a few of them slip through and if you are good at these things then maybe this is where you can contribute?

Besides the obvious typos and misspellings, here are two easy mistakes to keep an extra eye on: 

1. The classic “a vs. an”
   This is a tough one I know, I’ve probably used them incorrectly several times in this article. The rule is “a” comes before words starting with a consonant sound, and “an” before words with a vowel sound. Since this rule depends on how a word sounds I’ve found that it helps a lot if I sit somewhere I can read the documentation out loud and then I usually hear if it’s used incorrectly.
   
   
2. Use of different pronouns 
   I’ve found that when several people have contributed to the same piece of documentation, especially one that runs over several pages, sometimes they use different pronouns. A tutorial could start with something like “First we create a..”, and on page two it says “Now once I build the..” and then on the last page it goes “So as you can see..”. Classic mistake and easy to spot if you read the whole thing from start to finish.

Proofreading tutorials and docs

Take any tutorial in the documentation section and run it through from start to finish exactly the way it says. Make no assumptions and try to picture yourself being new to the subject or even new to Umbraco:

1. Did it make sense or did it assume that you already knew about x or y?
   Then it should probably say so in the beginning or at least explain it a little bit.
   
   
2. Did it compile?
   You should be able to copy-paste a complete code snippet into your code and it should compile right off the bat without you having to guess which namespace is missing. Did it contain locally declared variables outside of the provided code-snippet or did it contain obsolete services or methods?
   
   
3. Did the attached screenshots match the reality?
   Sometimes, as the design of the back-office evolves throughout the years, the screenshots for the tutorials might not and this could be a bit confusing for someone new to Umbraco.

These are just a few things to keep an extra eye on when you’re scanning the documentation in search for your first contribution. Reading through the documentation word by word can literally be done from anywhere in the world, from your phone or your laptop, plus it will also have the pleasant side effect of you learning a bunch of new stuff while doing so. 

The worst thing that can happen is the documentation is perfect and you didn’t find anything but you gained a ton of knowledge.

The Our community blogs

Blogging about Umbraco is obviously a contribution in itself and by doing so you’re helping the community to grow and become stronger with each new post, but did you know that just by owning a blog you automatically have your first pull request pretty much made for you?

I’m talking of course about the Our Umbraco blog posts. On the community site Our Umbraco, there’s a section called Blog Posts, which pulls Umbraco related blog posts using a JSON file located in the Our project. And since the Our project is open source, you can add your own blog's RSS details to this JSON file, and your blog posts will pop up on Our Umbraco.

It’s a win-win for everyone! You’ll get more traffic to your website, Umbraco’s community site will get more content plus adding your blog to this list actually counts as an actual pull request to Umbraco! Cool huh? More details on how to add your blog to this list is found here.

You don’t have a blog yet?

Why not? I bet you’d have an awesome blog! If you’re new to Umbraco it’s easy to assume that you don’t have anything valuable to write about or that you’re not experienced enough to have a blog. But that’s where you’re wrong. Since you are new, you’re learning new things every day and that’s why you are perfect for writing about it. Why? Because you remember what it was like not knowing it. No one will explain it better than you, trust me.

Experienced developers have a tendency to only want to write expert-level blog posts to other experienced developers. But what the community needs in order to grow and gain new Umbracians are more beginner-level blog posts (like this one) and if you are somewhat new to Umbraco then you are perfect for the job. Learn as you go along and write about it, I would love to read your blog. But don’t forget to add it to the Our community blogs so I can find you!

Yes, I did it! Now what?

So you’ve completed your very first pull request to Umbraco and you’ve submitted it for review?
Good job, #H5YR! (Not sure what this is short for? Please visit https://h5yr.com/about/)

Now you will have to wait a little while, which is probably the hardest part of contributing to Umbraco: the waiting. But it’s worth the wait. Eventually you’ll be contacted by a friendly HQ or Community member who will either approve your pull request straight away or give you feedback so that you can adjust your pull request before it can be approved and merged.

Once your pull request has been merged you’ll be a part of the already mentioned GitHub Contributors list on the start page of our.umbraco.org. That’s the beauty of this community, that you’ll be listed even if you’ve only done a single commit. Everyone counts!

Also, you will get a shiny new C-Trib badge on your profile on Our. Since this was your first pull request, make sure to contact Sebastiaan, he usually makes sure the new contributors get their well deserved badge. Once you get this badge, you’ll also be a part of The list of Contributors on Our.

And you know what else you’ll get?

A thirst for more! You’re already thinking about your next pull request, aren’t you? Maybe try going a little bit deeper in the water this time, taking on a slightly bigger task? Once you break that mental barrier of “I could never contribute to any of the Umbraco projects...” and you get that first pull request approved and merged, I promise you’ll feel a lot more confident for the next one. And since you’re now familiar with the whole process around submitting a pull request to Umbraco, you can focus less energy on the process and more on the actual issue you’re trying to solve.

Friends, thank you for your time.
Take care of each other and be safe.