Getting started contributing to open source isn't always easy. Usually, there's a whole new code base we need to understand before starting contributing. Sometimes it's well-documented, sometimes not. That's why I always recommend people to start with documentation first and code later. It's a perfect way to get started contributing without any specialized tooling or knowledge, and usually, open source projects always welcome updates to the documentation.
I've decided to create a guide on how to contribute to the Ember ecosystem starting with contributions that don't even require coding and ending up with something a bit more advanced. This is part one.
The Ember Times is a weekly newsletter made by a lot of different contributors. Some of them are members of the Core Teams, some of them have been writing for The Ember Times for a very long time, and some stop by to contribute once or twice. No matter which category you fall into, your contributions are always incredibly helpful and appreciated.
Usually, a contributor for the Ember Times will select a topic and then write a small section about that specific topic. There's often the misconception with contributions like this that we have to be experts to write about a particular topic. I can guarantee you that most people who contribute documentation - including me - don't know a whole lot about what they're about to document.
When I pick a topic, it's usually about something I don't know a whole lot about and that's perfectly fine. It's an excellent opportunity to learn.
The first steps
The first thing to do is to make sure that you're signed up for the Ember Discord chat. There is a channel named #support-ember-times. This is where all work regarding the newsletter is coordinated.
If you have never contributed to the Ember Times before it's a good idea to go and say hello. The Ember Times people are incredibly kind and will help you get started picking a topic if you need it.
For each week there is a work in progress pull request containing the draft of the newsletter as well as a list of potential topics to include. This pull request can be found in the channel topic of the Discord channel.
Let's have a look at one of the previous pull requests.
Here you can see that I have picked the topic "New guides are out containing angle bracket invocation syntax." This is not because I have a specific knowledge about angle bracket invocation syntax, but it's something I wanted to know more about.
When I've decided on a topic, I'll let the others know in the #support-ember-times channel.
Getting the Repo
Working with open source repositories does require some work with Git. If you haven't used Git before I suggest completing a small Git tutorial before you proceed.
First, visit https://github.com/emberjs/website and press the fork button. This will create a fork of the repository that you can work directly on. Think of this as a photocopy of an original document. You can draw all you want on the photocopy until you're satisfied with the result and it won't harm the original.
Once it's forked, it's time for some work in the terminal. In your terminal you need to clone your newly forked repository:
git clone URL
You can find the clone URL in your forked repository:
cd website/
Now, we have one remote source for this repository which is your newly forked repository. This is great for when we want to create the pull request in the end. But for now, we want to fetch the work-in-progress pull request containing the draft of the Ember Times issue.
Let's add the original repository as a remote source and call it upstream:
git remote add upstream git@github.com:emberjs/website.git
This means that we can fetch the branch containing the draft. The branch name can be found in the GitHub UI for the work-in-progress pull request.
git fetch upstream blog/embertimes-85
And then let's checkout to that branch:
git checkout blog/embertimes-85.
Now we're ready to create a branch that we want to work from. In my case I'll name it like this:
git checkout -b angle-bracket-guides
There are no rules for naming of your branch, but I like to include some reference to what it contains.
Writing The Section
The technical setup is done, and we're now ready to write some content. There are no rules on the length of the section, but I think the average is around 100 words. Ideally, we want to keep it short and sweet.
Even though I'll write about angle bracket invocation syntax, I aim to keep it non-technical. Any crucial technical information, code samples or things like this should ideally live in a separate guide or blog post that can be referred to in the Ember Times.
In this case, there's a new version of the Ember Guides containing this new syntax.
Again, there are no rules on how to do this but here's my process when I write:
I start by announcing the news right away while still keeping the reader interested.
"A new version of the Ember guides has been deployed, and it contains some exciting surprises."
Now since the new guides contain two new features I choose to start with the non-flashy one:
"First of all, the guides-source and guides-app repositories have become **one repository**. This makes it so much more convenient to maintain and contribute. It also now uses the Guidemaker technology which means that CLI-guides and the Ember guides are using the same tech."
And for the finale:
"And now for the big surprise: **The newly deployed guides now contains angle bracket invocation syntax**. So, if you're looking to use angle bracket invocation syntax in your Ember application, the guides are the place to look for help."
Now, as you might notice, this small section did not require me to have any special knowledge of the technical aspects of angle bracket invocation syntax for me to be able to write about the update.
Wrapping It Up
Now that we've finished the section there are only a few things left to do. As you'll notice in my pull request, I've added a few things besides the section itself.
In the very top, I add my name as an author. Everyone who writes a section for the Times should be credited as an author.
Next, I've added a one-sentence description of my section for the introduction. Don't worry about it being cohesive with the rest - that will happen in the final edit.
Lastly, I've added my name again at the bottom.
You're now ready to commit everything and push it to your fork:
git add blog-file-name
git commit -m "Added section on new guides"
git push origin angle-bracket-guides
If you visit your forked repository, you will now be able to create a pull request targeting blog/embertimes-85.
When that's done, you should post a link to the pull request in the #support-ember-times channel, and one of the team members will review your pull request.
Your Actions
Are you ready to get started?
- Go to the Times channel, find the work-in-progress pull request.
- Pick a topic and let the Times people know.
- Fork and clone the repository.
- Start writing a small section.
- Add your name and an intro.
- Send it for review.
If you get stuck or need any help, please reach out to the fantastic Ember Times people in the Times channel on Discord.
That's it for getting started contributing to the Ember Times. Stay tuned for the next post in this series where will write a section for the release post together.
Top comments (0)