How to contribute content for Umbrella ^[a]

A beginner tutorial for editing content hosted in a GitHub repo using prose.io

Read this if: 

• You use our free, open-source Android or iOS app, Umbrella, and you want to propose a correction or update some content using a GitHub workflow.
• You know your way around Microsoft Office but GitHub is outside your comfort zone.
• You think Git is an old school British insult and Markdown sounds like a dance move by the Funky Bunch, but you’re willing to learn otherwise.

Skip this if:

• You just want to tell us about one tiny thing and you don’t have bandwidth for a tutorial right now. (Email a short description of the change you want to propose to  info@secfirst.org.)
• You already use GitHub but you don’t have time to create a pull request right now. (Open an issue in our Tent content repo.)

BEFORE YOU START

What is Umbrella? Umbrella is a free, open-source Android and iOS app with the latest security advice for NGOs, journalists, and aid workers. Get Umbrella from Google Play, iOS Store, Amazon, or F-Droid.^[1] 

What is Git, and what is GitHub?  Git is a version control system used for coding. GitHub is an online platform for managing code using Git. Coders can easily test and refine projects on GitHub, because any number of people can copy the same project and make changes simultaneously. GitHub records every change using Git, and the project owner can approve all of them, or none, or any combination. A folder, or directory of version controlled files is called a repository (repo).  

What is Markdown? Markdown is an easy way for non-coders to format text that can be used directly in an app or a website. It’s like a compromise between word documents and HTML. Any file with the .md extension was written in Markdown.  

Why manage content this way? It’s like track changes, only better.

1. It’s better for security, because if @unknownactor or @badguy wants to delete or replace content, you can see the attempt and stop it.
2. It’s more transparent, because anyone can see what we create and can weigh in or repurpose it for their own projects.
3. It’s better for wrangling content with several authors, because there’s less copy paste.

✘ No copy pasting word documents into a CMS.

✘ No copy pasting edits from different people into your master version.

✘ No copy pasting Edit.1.1 next to Edit.1.2 to check your colleague added that feedback from your boss.

So why doesn’t everyone do it? Some people think everyone should. Other people think everyone will soon. But Git and Markdown still represent a barrier to non-coders. A lot of tutorials require you to open a terminal, clone something, and use the command line. We won’t, though, so don’t worry if those phrases sound like they belong more in a sci-fi action thriller than your office. You can do everything in this tutorial on github.com, otherwise known as GitHub web interface or UI. So if you have questions that aren’t answered here and need to look around for a solution, add those terms to your search.  

Why not just use Google docs? A Google doc allows collaboration and has some basic version control features, but can be hard to police once you share it publicly. Plus, don’t you hate other people watching you type? GitHub edits are visible, but only once you hit publish (or in GitHub parlance, commit).

If I can do it, you can.   I’m Madeline Earp, and I manage Umbrella content. I have a literature degree and researched human rights and freedom of expression issues for ten years before I joined Security First. So I know a few shortcuts in Microsoft Word, but my idea of advanced computing is to open Excel. I use GitHub for content, and I wrote this guide to let you know: It’s not so bad. I’m still scared I’ll break something or forget to spellcheck, and while I’m for transparency in theory, the idea of leaving a visible trail of every mistake I make along the way takes some getting used to (pro tip: the vast majority of people couldn’t care less. Anyone that does care is helping you fix it). But while I’m still no expert, the GitHub workflow has helped me understand the architecture of sharing digital information much better than typing into a document built to look like a sheet of paper. I’ve also heard plenty of first hand reports of hackers hijacking digital content to spread misinformation, or phish for personal data. I’m OK spending a bit of time to make that outcome less likely, and I hope you’re willing to give it a try too.

TOOLS WE’LL BE USING

GitHub

Prose.io, a Markdown editor for GitHub^[2] 

Google Chrome browser

1. FIND THE RIGHT REPO

Go to https://github.com/.

If you don’t have one already, create an account. Your username acts like a signature for any changes you make.

Once you’re logged in, type “security first” in the search bar, and hit enter.  

The default will display repositories called security first. Instead, click on “users.”

You found us! Now click on securityfirst.

On the Security First page, scroll down the list of repositories until you find one called tent-content. Click on this, not umbrella-content, which is a one-time export of content that is not updated.

2. FORK THE REPO

Click on the Fork button. GitHub will ask you where to fork the repository to—just click on your own icon/username.

If everything works out, you should see your own username next to tent-content at the top of the page. Here’s what mine looks like:

Keep this tab open.

3. OPEN PROSE.IO

Type prose.io into a new browser tab. Click “Authorize on GitHub.”

When prompted, enter your GitHub credentials.

Prose will list projects you’re working under your GitHub username. Click on tent-content.

Prose will show you what’s inside the tent-content repo and give you the option to edit any file written in Markdown, with a .md extension. It will look something like this:

Before we start, we’re going to change which version we’ll be working on. Click on the pull down menu “Switch Branch” on the right-hand side of the screen. A branch is just a version, like a draft.

Tent-content has a few branches for different kinds of updates. Prose will select the master branch by default, but we’ll be working in one called “difficulty.”^[3] Click on “difficulty” in the pull-down menu.

Now that you’re in the difficulty branch, you’ll see different content folders organised by language (contents_en for English, contents_es for Spanish, etc). Click on the language you want to edit. I’ll be using English for this tutorial.

Spend a minute clicking around the folders to get a sense of how the content is arranged compared to what you see in Umbrella.  

4. MAKE YOUR CHANGE

For this tutorial, I’m going to correct the “What Now?” page of the Managing Information chapter. It appears under the Information section, so the folder I’ll click first is the one called information. Inside the information folder, I’ll click on managing-information, then beginner (all lessons will group content in a beginner folder, even if there is no advanced level).  

Now I’ll click on the file I want to edit, what-now.md. You can click on the title, or on the Edit button to open a file.  

Prose will open the content in a window that you can edit like a word processor. Try it out by clicking anywhere and typing something—no-one will see it until you click save. Here I’m correcting a spelling mistake:

When you’re happy with your changes, click on the “save” icon.

In the pane on the left (“Review your Changes), Prose will show you what you changed.

In the window on the right (“Describe your Changes”), type a brief summary of your changes (“correct spelling in what-now.md”). This tells Security First and other people on GitHub what you’re doing.  

When you’re comfortable with your changes, click “Commit.” This isn’t irreversible, but others will be able to see it from this point.

Close Prose.io.

5. CREATE A PULL REQUEST

Return to the tab that shows your tent-content fork.

So far, your commit with the changes you made are only on your page. Now you have to ask Security First to review them. You can do that by opening a Pull Request.

Click in either of these places.

In the next window, type a brief summary of your changes in the Title and/or Leave a comment area. Like before, this lets us know what you’d like to change.

If you like, add my name (madelineearp) to the pull request by clicking “Assignees” in the right-hand menu. (Even if you skip this step, Security First will still see the pull request.)

Then click “Create pull request.” You did it!

6. WHAT HAPPENS NEXT?

We’ll review the pull request, and get back to you if we have a question. More likely, we will go ahead and merge it, meaning we will accept the change and incorporate it into Umbrella. You can watch the progress of the pull request on github, and it will stay public for the record even after we act on it.

Here’s the commit with my spelling change after it was merged: https://github.com/securityfirst/tent-content/commit/0d041057fcde46c08e791f0e70a5d7444718c71e.

To view the accepted change in Umbrella itself, click Settings, the three vertical dots at the top right. Then click “Refresh from server.”

THANK YOU!

We’re a startup, which means we’re really busy and don’t get to review every pull request immediately, let alone shower our contributors with the thanks they deserve. But we’re really grateful that you’re interested in Umbrella, that you took the time to read this tutorial, and for any contribution you can make to the content. Please let us know how the process worked for you!