Open-source News

7 Git tips for technical writers Maximilian Kolb Mon, 11/21/2022 - 03:00

As a technical writer working for ATIX, my tasks include creating and maintaining documentation for Foreman at github.com/theforeman/foreman-documentation. Git helps me track versions of content, and to collaborate with the open source community. It's an integral part of storing the results of my work, sharing it, and discussing improvements. My main tools include my browser, OpenSSH to connect to Foreman instances, Vim to edit source files, and Git to version content.

This article focuses on recurring challenges when taking the first steps with Git and contributing to Foreman documentation. This is meant for intermediate Git users.

Prerequisites

• You have installed and configured Git on your system. You must at least set your user name and email address.

• You have an account on github.com. GitHub isn't an open source project itself, but it's the site where many open source Git repositories are stored (including Foreman's documentation.)

• You have forked the foreman-documentation repository into your own account or organization (for example, github.com/My_Name/foreman-documentation. For more information, see A step-by-step guide to Git by Kedar Vijay Kulkarni.

• You have added your SSH public key to GitHub. This is necessary to push your changes to GitHub. For more information, see A short introduction to GitHub by Nicole C. Baratta.

Contributing to Foreman documentation

Foreman is an open source project and thrives on community contributions. The project welcomes everyone and there are only a few requirements to make meaningful contributions. Requirements and conventions are documented in the README.md and CONTRIBUTING.md files.

Here are some of the most frequent tasks when working on Foreman documentation.

I want to start working on Foreman documentation

1. Clone the repository from github.com:

   $ git clone git@github.com:theforeman/foreman-documentation.git
   $ cd foreman-documentation/

2. Rename the remote:

   $ git remote rename origin upstream

3. Optional: Ensure that your local master branch is tracking the master branch from the foreman-documentation repository from the theforeman organization:

   $ git status

   This automatically starts you on the latest commit of the default branch, which in this case is master.

4. If you do not have a fork of the repository in your own account or organization already, create one.

   Go to github.com/theforeman/foreman-documentation and click Fork.

5. Add your fork to your repository.

   $ git remote add github git@github.com:My_Name/foreman-documentation.git

   Your local repository now has two remotes: upstream and github.

I want to extend the Foreman documentation

For simple changes such as fixing a spelling mistake, you can create a pull request (PR) directly.

1. Create a branch named, for example, fix_spelling. The git switch command changes the currently checked out branch, and -c creates the branch:

   $ git switch -c fix_spelling

2. Make your change.

3. Add your change and commit:

   $ git add guides/common/modules/abc.adoc
   $ git commit -m "Fix spelling of existing"

   I cannot emphasise the importance of good Git commit messages enough. A commit message tells the project maintainers what you have done, and because it's preserved along with the rest of the codebase, it serves as a historical footnote when someone's looking back through code to determine what's happened over its lifespan.

4. Optional but recommended: View and verify the diff to the default branch. The default branch for foreman-documentation is called master, but other projects may name theirs differently (for example, main, dev, or devel.)

   $ git diff master

5. Push your branch to Github. This publishes your change to your copy of the codebase.

   $ git push --set-upstream github fix_spelling

6. Click on the link provided by Git in your terminal to create a pull request (PR).

   remote: Create a pull request for 'fix_spelling' on Github by visiting:
   remote:      https://github.com/_My_User_Account_/foreman-documentation/pull/new/fix_spelling

7. Add an explanation on why the community should accept your change. This isn't necessary for a trivial PR, such as fixing a spelling mistake, but for major changes it's important.

More on Git What is Git? Git cheat sheet Markdown cheat sheet New Git articles I want to rebase my branch to master.

1. Ensure your local master branch tracks the master branch from github.com/theforeman/foreman-documentation, not foreman-documentation in your own namespace:

   $ git switch master

   This should read Your branch is up to date with 'upstream/master', with upstream being the name of your remote repository pointing to github.com/theforeman/foreman-documentation. You can review your remotes by running git remote -v.

2. Fetch possible changes from your remote. The git fetch command downloads the tracked branch from your remote, and the --all option updates all branches simultaneously. This is necessary when working with additional branches. The --prune option removes references to branches that no longer exist.

   $ git fetch --all --prune

3. Pull possible changes from upstream/master into your local master branch. The git pull command copies commits from the branch you're tracking into your current branch. This is used to "update" your local master branch to the latest state of the master branch in your remote (Github, in this case.)

   $ git pull

4. Rebase your branch to "master".

   $ git switch my_branch
   $ git rebase -i master

I have accidentally committed to master

1. Create a branch to save your work:

   $ git switch -c my_feature

2. Switch back to the master branch:

   $ git switch master

3. Drop the last commit on master:

   $ git reset --soft HEAD~1

4. Switch back to my_feature branch and continue working:

   $ git switch my_feature

I want to reword my commit message

1. If you only have one commit on your branch, use git amend to change your last commit:

   $ git commit --amend

   This assumes that you don't have any other files added to your staging area (that is, you did not run git add My_File without also committing it.)

2. Push your "change" to Github, using the --force option because the Git commit message is part of your existing commit, so you're changing the history on your branch.

   $ git push --force

I want to restructure multiple changes on a single branch

1. Optional but strongly recommended: Fetch changes from Github.

   $ git switch master
   $ git fetch
   $ git pull

   This ensures that you directly incorporate any other changes into your branch in the order they've been merged to master.

2. To restructure your work, rebase your branch and make changes as necessary. Rebasing to master means changing the parent commit of your first commit on your branch:

   $ git rebase --interactive master

   Replace the first word pick to modify the commit.

   • Use e to make actual changes to your commit. This interrupts your rebase!

   • Use f to combine a commit with its parent.

   • Use d to completely remove the commit from your branch.

   • Move the lines to change the order of your changes.

     After successfully rebasing, your own commits are on top of the last commit from master.

I want to copy a commit from another branch

1. Get the commit ID from a stable branch (for example, a branch named 3.3), using the -n option to limit the number of commits.

   $ git log -n 5 3.3

2. Replicate changes by cherry-picking commits to your branch. The -x option adds the commit ID to your commit message. This is only recommended when cherry-picking commits from a stable branch.

   $ git switch My_Branch
   $ git cherry-pick -x Commit_ID

More tips

At ATIX, we run a GitLab instance to share code, collaborate, and automate tests and builds internally. With the open source community surrounding the Foreman ecosystem, we rely on Github.

I recommend that you always point the remote named origin in any Git repository to your internal version control system. This prevents leaking information to external services when doing a git push based on pure muscle memory.

Additionally, I recommend using a fixed naming scheme for remotes. I always name the remote pointing to my own GitLab instance origin, the open source project upstream, and my fork on Github github.

For foreman-documentation, the repository has a relatively flat history. When working with a more complex structure, I tend to think of Git repositories in a very visual way with nodes (commits) pointing to nodes on lines (branches) that potentially intertwine. Graphical tools such as gitk or Git Cola can help visualize your Git history. Once you have fully grasped how Git works, you can move on to aliases, if you prefer the command line.

Before a big rebase with a lot of expected merge conflicts, I recommend creating a "backup" branch that you can quickly view diffs against. Note that it's pretty hard to irreversibly delete commits, so play around in your local Git repository before making big changes.

Git for tech writers

Git is a tremendous help for technical writers. Not only can you use Git to version your own content, but you can actively collaborate with others.

Follow along with this demo of how I use Git to write documentation for Foreman.

Image by:

Jonas Leupe on Unsplash

Git Documentation What to read next How writers can get work done better with Git This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License. Register or Login to post a comment.

5 htop Alternatives to Monitor Your Linux System  It's FOSS

Last week with Linux 6.1-rc5 there was concerns raised by Linus Torvalds that the v6.1 cycle may need an extra week of testing and fixes. Now Linux 6.1-rc6 is available with Torvalds' latest prognosis for the Linux 6.1 kernel cycle...

Linux 6.1-rc6 Released - Still Coming In Larger Than Torvalds Would Like  Phoronix

Linux Foundation Adopts Microsoft Framework for Supply Chain Security  SDxCentral

Accidentally Removed Your Sole Ubuntu User From All Groups? Here's How to Fix It  MUO - MakeUseOf

While Razer still sadly isn't officially supporting their various gaming-focused computer peripherals under Linux, the OpenRazer project providing open-source drivers for Razer products continues working out well and offering broad hardware support under Linux...

OpenRazer 3.5 Brings Support For Newer Razer Devices On Linux  Phoronix

One of countless great open-source projects from Intel over the years is IWD as a modern wireless daemon for WiFi devices on Linux. IWD has been in the works for over a half-decade as a new replacement to wpa_supplicant and with time has implemented many features and seen widespread adoption. Released this week was IWD 2.0 as the latest milestone for this open-source wireless daemon...

Intel's IWD 2.0 Released For Modern Linux Wireless Daemon  Phoronix

Since the introduction of the AMD P-State driver to the mainline kernel, enthusiasts and gamers have been experimenting with the amd_pstate driver and some distributions like Ubuntu have went with using this driver in place of ACPI CPUFreq by default for Zen 2 and newer processors. Patches posted this week by AMD make it easier to switch between the AMD P-State driver and ACPI CPUFreq...

In addition to Linux 6.2 promoting [DG2] Arc Graphics to stable, this next kernel version will no longer deem the Intel In-Field Scan (IFS) driver as "broken" now that it's API/ABI is in good shape...

Fixed Intel IFS Driver Ready To Go With Linux 6.2  Phoronix

New Patches Allow More Easily Managing The AMD P-State Linux Driver  Phoronix

Thanks to this year's Linux Plumbers Conference it looks like the compute accelerator subsystem/framework is finally coming together. The fourth and potentially final iteration of the accelerator framework patches have been sent out with hopes of them being mainlined for the upcoming Linux 6.2 kernel...

Compute Accelerator Subsystem Hopes To Be Ready For Linux 6.2  Phoronix

Libinput 1.22 was released this weekend by José Expósito as the newest version of this widely-used input handling library that is now common to the Linux desktop by both X.Org and Wayland based environments...

Libinput 1.22 Brings More Input Hardware Quirks, New Flat Acceleration Profile  Phoronix

Week in review: 5 Kali Linux tools, Spotify’s Backstage vulnerability, Cybertech NYC 2022  Help Net Security

Get verified on Mastodon with WordPress Seth Kenlon Sun, 11/20/2022 - 03:00

As users migrate away from Twitter, many wonder what the equivalent of the famous blue checkmark is on Mastodon. Ignoring debates about how anyone can be sure of anyone's true identity online, it's easy to verify yourself on Mastodon when you have a WordPress site.

1. Get your verification code

Sign in to your Mastodon account and click the edit profile link under your Mastodon handle.

Image by:

(Seth Kenlon, CC BY-SA 4.0)

In the Edit Profile screen that appears, scroll down to the Verification section. This section contains a special verification code. Click the Copy button to copy your verification code to your clipboard.

Image by:

(Seth Kenlon, CC BY-SA 4.0)

More open source alternatives Open source project management tools Trello alternatives Linux video editors Open source alternatives to Photoshop List of open source alternatives Latest articles about open source alternatives 2. Paste your code on your WordPress site

To assure people that the same person running your Mastodon account also runs your website, you must paste your verification code into your WordPress site. You can create a post to serve especially for this purpose, or you can put it into your site's footer, or you can make it a social link.

The easiest method is to create a special post to serve as your verification page. In your WordPress dashboard, click the Posts link in the left panel, and then select Add New.

In the post editor, give your post a title, and then type the word "Mastodon" into the body. You can type more than just the word "Mastodon," of course. You might want to type a nice post about your new social network, inviting people to join you there and follow you. Or you might keep it simple. It's up to you.

Once you've got some text, hover your mouse over the text block in WordPress until a pop-up toolbar appears. Click the three-dot icon ("Options") and select Edit as HTML.

Image by:

(Seth Kenlon, CC BY-SA 4.0)

This exposes the HTML code inside the text block. Don't worry, you don't need to know how to code for this to work. Select the word "Mastodon" in the text block, and then paste your Mastodon verification code in its place.

Click the Update or Publish button in the top right corner of the WordPress editor interface. Your post must be published for Mastodon to detect your link.

3. Add your post URL to Mastodon

Once your verification post is published, visit the page and copy the web address from your web browser's URL bar. For example, the sample post I wrote is located at http://myexamplewebsite.tk/wp/uncategorized/i-joined-mastodon.

In your browser, return to the Edit Profile screen of Mastodon. Locate the Profile Metadata section, and type Website into the Label field and then paste the URL of your verification post in the Content field.

Image by:

(Seth Kenlon, CC BY-SA 4.0)

Click the Save Changes button and return to your profile page to see your newly verified status.

Image by:

(Seth Kenlon, CC BY-SA 4.0)

On some Mastodon servers, it seems that verification may take an hour or so to resolve, but on two of the three I've tested, the green checkmark appeared immediately after saving.

Verifiably cool

Strictly speaking, the word "Mastodon" in the verification code is arbitrary. In this article, I've encouraged using that because it's the default and most obvious word to link back to your Mastodon profile. However, if you're interested in the technical aspect, then what really matters is that a link to your profile page, with the rel="me" attribute, appears on a page of a website you control. The contents of the link don't actually matter.

A green checkmark on Mastodon indicates proof that the same person controlling your Mastodon account also controls your website. Ultimately, that's as good as "identification" gets on the Internet. Blue checkmarks might look and feel official, but identification services online can't ever guarantee that a person at a computer is the same person from one day to the next. Mastodon acknowledges this and offers verification options for every user. With a no-cost WordPress blog and a no-cost Mastodon account, you can demonstrate to your friends that the same person (you) posting on the blog is the same person active on social media.

Three steps to verify your Mastodon account with WordPress.

Image by:

CC BY 3.0 US Mapbox Uncharted ERG

Alternatives WordPress What to read next Get verified on Mastodon with your website This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License. Register or Login to post a comment.