OpenStreetMap

Making a simple textual change to the "switch2osm.org" site

Posted by SomeoneElse on 23 December 2019 in English (English)

As you may be aware, the “switch2osm” site recently moved from Wordpress to Github. This means that it’s easy to request changes to the site over at the github repository. Any changes made there will automatically go live on the main site after a minute or so.

“Requesting changes” might mean commenting on existing issues or creating new ones (which will need someone else to make the code or text changes you’ve requested), or it might mean suggesting the changes yourself via a “pull request” - a list of specific changes you’d like to see made. Here is an example of a pull request - you can see what it’s a change from and to, and on this page you can see any comments and when it was merged in and by whom.

Obviously, if people can contribute via pull requests rather than just creating issues it’s better for everyone - it means that you’re not relying on someone else reinterpreting the changes that you’d like making, and it’s quicker for the maintainers too.

Normally if you wanted to make a major change to something on this site you’d “fork” a copy of the repository into your own github area, create a “branch” from that that relates to the change that you’d like to make, “clone” that locally into an environment on a local machine that allows you to test the site locally, make your changes, test your changes in a local web browser, submit your changes back to your copy of the site, and then create a pull request explaining the change you’d like to make.

What you may not know is that for simple textual changes you can actually do the whole process online. That’s not appropriate for anything that might break links, but for simple text changes (like the example above) it’ll work just fine, and this is what the rest of the diary entry describes.

If you don’t have a github account already, go to https://github.com/switch2osm/switch2osm.github.io. If you don’t have a github account click “sign up” at the top; if you do have a github account already, continue from “Next, at the top right” below.

Select a plan - for the purposes of this exercise “individuals” and “choose free” will work just fine. Then “complete this step”.

That takes you back to https://github.com/switch2osm/switch2osm.github.io.

At the top of the screen there’s a big green button labelled “read the guide”. That’s a useful introduction - you can either read it now or click on the link later.

While that was happening, you’ll have been sent a “Please verify your email address” email from Github. Click through the link from there to prove that you are who you say you are.

Next, at the top right of the https://github.com/switch2osm/switch2osm.github.io page (just below “read the guide”) there’s a button labelled “Fork”. The tooltip says “Fork your own copy of switch2osm/switch2osm .github.io to your own account”. Click that.

Wait a few seconds. When the repository appears you’ll get a prompt to “set up github actions” - you can dismiss that for now.

You’ve now got your own copy of the “switch2osm” github repository. Next, you’ll want to create a branch to hold your changes. In this example I want to make a small textual change to how “renderd” is described on one of the “manually building a tile server” pages, so I’ll call it “renderd_text_change”. From your copy of the repository (something like “https://github.com/yourgithubusername/switch2osm.github.io”), To create a branch, click on where it says “Branch master”, type in the new name and click “create”.

Now browse to the page that you’d like to change. In my example it’s “https://github.com/mygithubusername/switch2osm.github.io/blob/renderd_text_change/serving-tiles/manually-building-a-tile-server-18-04-lts.md”. It’s just a text file in Markdown format. At the top right-hand corner there’s an edit button. Click that, and make the necessary changes.

When you’re happy that your change is complete, at the bottom of the screen type in a short one-line summary of your change followed by a longer description. Ensure that “Commit directly to the branch" is displayed (not "master"). Click "commit changes".

Go back to “https://github.com/yourgithubusername/switch2osm.github.io”. You’ll now see that the screen now shows “Your recently pushed branches:” and gives you the opportunity to “Compare & Pull Request”. Click that. Review your change (old version on the left, new version on the right), and change your summary and description if you want. When you are happy, click “Create pull request”.

Github will then take you out of your copy of the repository into the new pull request in the repository that you forked your copy from. In this example, that’s here. If you scroll down the page a bit you’ll see that initially some background checks are taking place, and then eventually “All checks have passed” and “This branch has no conflicts with the base branch”. You, and other people, can comment on your proposed change. Someone will review it and (probably) merge it without comment. It’ll then be live for all to see at https://switch2osm.org/.

Comment from mmd on 23 December 2019 at 22:28

There’s really no need to fork the repository on your own. Just go to https://github.com/switch2osm/switch2osm.github.io, locate the file you want to change, and hit the edit (“pencil”) icon. Github will automatically fork the repository for you in the background and guide you through the pull request process without much hassle. It’s really that simple.

Comment from ConsEbt on 23 December 2019 at 23:29

This is great on many levels. Found already one thing I will ‘correct’ or enhance.

Comment from tordans on 26 December 2019 at 05:41

Thanks @mmd. The quick-edit-fork-and-PR-flow is really awesome and easy and I was surprised to see it’s a feature since 2011 https://github.blog/2011-04-26-forking-with-the-edit-button/ (but was improved a lot since those screenshots).

Login to leave a comment