Hangprinter.org Contribution Guide via Gitlab

Hangprinter.org's sources, as well as the rest of the Hangprinter Project, is hosted on Gitlab. This guide shows how to submit an improvement to a Hangprinter documentation page.

Step 1: Get a Gitlab Account

Navigate to gitlab.com's sign in page, and find the "register now" link.

Click the image for a larger version. Works for all images in this guide.

Fill in your details in the registration page, like this:

After you click "Register" you will receive an email that asks you to verify. Follow the "Confirm your account" link in this email.

After this, you should be able to go back to gitlab.com's sign in page and sign in with your new username and password.

Upon signing in, you'll might also receive an email from Gitlab with subject "Fix your pipelines by validating your account". Pipelines are an advanced Gitlab feature, and you don't need to fix them. You can safely ignore this email.

Don't worry about pipelines or runners. Ignore this email.

Step 2: Create a Fork

In this example, we'll make a change to the documentation shown on hangprinter.org/doc/v4. Head over to the repo where it's hosted: https://gitlab.com/tobben/hangprinter-org.

There's a lot of details on the repo page, but all we need for now is to click the button saying "Fork".

We'll land on a page with many choices. We choose our namespace in the drop-down menu (there will be only one), select public visibility, and click "Fork project".

... which brings us to another repo page. This our forked repo. The word "fork" just means "registered copy".

Step 3: Make Your Change

In our forked repo, we click the "doc" directory.

We want to make a change to hangprinter.org/doc/v4, so we click the "v4" directory.

The file we want to change, the one that shows up at hangprinter.org/doc/v4, is called index.html. We click it to view its contents.

We will see all the text that our web browsers receives when we surf to hangprinter.org/doc/v4. To the human eye it looks a bit cryptic at first. However, this is the file that we need to change.

We click the button saying "Open in Web IDE".

The Web IDE is basically a text editor inside your browser.

The Web IDE.

Say we found and fixed a little error in the doc/v4 text. On line 131, it said "spacers that are twice as long". It should really say "spacers that are more than twice as long".

We add the words "more than" in the right place, and press the "Commit" button.

This brings up a page that lets you review your change. Scrolling down to line 131 indeed shows that the words "more than" have been added.

Once we've reviewed my own change enough, we press "Commit" down in the bottom left corner. Make sure the "Start a new merge request" checkbox is ticked.

Upon clicking "Commit", a merge request is created. This might trigger Gitlab to send us two emails with subjects "Fix your pipelines by validating your account" and "hangprinter-org | Failed pipeline for tobben_test_user-master-patch-03896 | 71e13f86". We can safely ignore these emails.

Step 4: Create the Merge Request

Since we chose "Start a new merge request" in the previous screen we arrive directly at the merge request creation screen.

There's nothing in particular we need to do here. So we just press "Create merge request".

Aaaand, we're done.🎉🎉🎉 All that's left is to wait for me (in my role as the project maintainer) to approve your merge request. After I've approved, the merge request page looks like this:

Among all the clutter there, you might see that the merge triggered a pipeline. It will run for 2 minutes and succeed. After that, the change is live and published. Here's a screenshot of hangprinter.org/doc/v4 a few minutes later.

Thanks for following along, and good luck with your doc changes! If you want to do more advanced things in the repos, don't hesitate to get in touch.

Why Gitlab?

This same contribution procedure applies to all Hangprinter related repos, code and documentation alike. It's a bit bulky in the smallest use case, like the one above, and it's a bit of a hassle to do on a smartphone (but it works!). The upside is that it scales up incredibly well, and all you need is a web browser, which is quite powerful.