Git: How to finish a PR for someone who is away on vacation

In this video, I demonstrate the following procedure using a colleague’s PR as an example.

How to get a copy of someone else’s pull request from Rolfe Dlugy-Hegwer on Vimeo.

Suppose you work with someone who is away for the Thanksgiving or Christmas holidays. What if you need to make changes to their pull request and get them merged before they return?

Prerequisites

You and your colleague both have forks of the same upstream repo.

You have already cloned your fork of the repo to your local machine and set up the upstream remote.

Procedure

Change to your repo directory. For example, enter:

$ cd openshift-docs

Add a remote that points to your colleague’s fork of the repo, as shown in the video. You go to GitHub, find your colleague’s PR, go to their fork, copy the URL of their fork, and paste it into the following command. Also name the remote you’re creating. This name can be an arbitrary string, but I recommend using the person’s first name. 

$ git remote add <remote-name> <url-of-their-fork>

For example, enter:

$ git remote add roberto git@github.com:bob007/openshift-docs.git

Create a working branch:

$ git status
$ git checkout -b <working-branch-name>

For example, enter:

$ git status
$ git checkout -b  xyz-456

On GitHub, return to the PR, copy the name of the other user’s working branch, and paste it into the following command:

$ git pull <remote-name> <remote-branch>

For example, enter:

$ git pull roberto abc-123

Git displays a commit message, usually in vi, that says something about the merge you just performed. In vi, you can save this commit message by pressing the Esc, :, w, and q keys.

In your local working branch, open one of the files you know your colleague changed in their PR. If you’ve done everything correctly, you should be able to see changes from their PR in your local working branch.

Make your changes to the content.

When you’re ready, push the changes by entering:

$ git push origin HEAD

Create a pull request for your working branch on GitHub by visiting the remote URL shown in the command output from the previous command. Right-click the URL and select open. For example:

remote: Create a pull request for 'xyz-456' on GitHub by visiting:
remote:      https://github.com/yourusername/openshift-docs/pull/new/xyz-456

Additional resources

https://stackoverflow.com/questions/21255057/how-to-fetch-someone-elses-pull-request-to-fix-it

Video: How to use Vale on the command line

How to use Vale on the command line from Rolfe Dlugy-Hegwer on Vimeo.

NOTE: This is a silent video without narration. For the best viewing experience, maximize the screen and set the video quality to 720p.

Here, using the Linux CLI shell prompt, I show you how to:

Check out your working branch by using git.

  • Run the Vale style linter on a specific asciidoc file with no options, so that you can see all the suggestions and errors from Red Hat style.
  • Run Vale again with the –minAlertLevel option to display errors only.
  • Get the line number from each error message to find and fix a handful of errors in the asciidoc file.

For more information, see:

Podcast episode: Mike McKiernan at Red Hat on using Git Pre-commit to automate adding metadata to content files”

Diagrams help your readers understand. Chris Metz gives "A brief demonstration of Mermaid.js" – Write Open Source

This episode is a video demo, which you can see here on spotify or vimeo.   Chris Metz is a freelance solutions architect and tech writer with cloud and emerging technologies based in Danville, California, near the San Francisco Bay Area.  In "A brief demonstration of Mermaid.js," Chris  shows us how to use Mermaid.js to add diagrams to your documentation.  Chris recently added the Diagram Guide to the Kubernetes.io website, where he is a regular contributor. To me, this diagrams-as-code has several benefits: It separates the content of the diagrams from how they are presented, which means that all your diagrams have a consistent look. The search results will include your diagrams when you edit and search your docs. Writers and developers can directly create diagrams without using specialized tools or creating asset files that get lost. — Send in a voice message: https://podcasters.spotify.com/pod/show/write-open-source/message
  1. Diagrams help your readers understand. Chris Metz gives "A brief demonstration of Mermaid.js"
  2. Jim Angel, Infrastructure Cloud Consultant at Google, on how NOT getting a $1/hr raise launched his tech career
  3. Tim Bannister on contributing to the Kubernetes.io documentation
  4. Mike McKiernan at Red Hat tells us about using Git Commit to automate adding metadata to his content files

Transcript

Rolfe: I heard in a recent meeting that you were working on a script that’s going to insert information about the assemblies into the top of the module. Tell me how this came about: how did you start working on it?

Mike: So pre-commit is a system that’s sort of like a framework that’s been put together in Python, and it’s broadly applicable for anything related to Git. It’s not related to documentation. It’s okay for software development and may even be more popular with software development.

The upshot is that, uh, right after you run a Git add, and you add the modules or the files you want to put into the commit when you run git commit, it runs what are called these Git pre-commit hooks.

And, in this particular case, the pre-commit hook is just a Python program that receives a list of the files that are in the commit and can distinguish between the modules and the assemblies.

And then for any of the modules that are updated, if there are any modules to be updated in the commit, races through the repo, figures out the relationship between assemblies and all the modules, and then updates any modules you might have.

And, I mean, I don’t know if it’s apparent to the audience, but it’s a tedious task, and it’s the kind of thing that you definitely want to have software do for you.

Rolfe: How did the initial request from this come up?

Mike: I guess the initial request was that this was a task that we used to do for all Red Hat documentation – that’s my understanding – and then the requirement for writers to keep this information updated seemed to fall by the wayside due to the Modular Docs steering committee. And I definitely adopted that freedom to not update this information as soon as that was even hinted at.

And then, but we subsequently learned through team meetings that our DPM (Document Program Manager) was interested in continuing to have this information updated. And at that point, I guess it was really sort of just a selfish desire to get myself out of that business because, as I said, I really don’t have any interest in gathering that information, keeping it up to date. It’s just, again, the perfect job for a computer–a bad job for a human.

Rolfe: Yeah. So you were solving a problem for yourself and helping other people at the same time.

Mike: It’s very, yeah, it was definitely, uh, absolutely selfishly motivated. No argument there, whatsoever, but I guess just sort of in the spirit of, uh, collaboration, teamwork, caring about people I work with. And then part of it’s the red hat ethos of open source and sharing.

I just offered…I shared with the team my experience and offered to support anybody who was interested in following that path of using pre-commit to use that hook.

Rolfe: So where’s the project now?

Mike: https://github.com/mikemckiernan/module-used-by, I think, is the name of the repo, but certainly it’s easier to type in sort of, uh, write down. In terms of status, I believe I’m complete with it.

Rolfe: Thanks. Is there anything else that you’d like people to know about this project or any thoughts?

Mike: Uh, only that it’s pre-commit is one…So within pre-commit, if this doesn’t sell you on pre-commit, that’s fine. Um, but just as an awareness across the writing group and anyone else at Red Hat, pre-commit is a really awesome way to automate any kind of a check.

There is a really strong series of hooks that are related to markdown that can run linters on your markdown, that can reformat your markdown, and it really can help enforce consistency across the repo. And it’s very opinionated, and the benefit there is that, then there’s very little time spent amongst contributors over, sort of, these like tiny details about layout, things like that, that really are not super important for the end-user, right, and so it just, it, it cuts through those sort of disagreements.

Rolfe: Thank you. I really appreciate your taking the time, and we’ll talk again soon. Okay.

Mike: Very cool. Thanks, Rolfe. Have a good weekend.

Rolfe: You too. Have a good weekend. Bye.

I’m going to try making a podcast

I spend a lot of time thinking about the nature of my profession and the people I work with. Now, I’ve created a podcast so I have an excuse to talk to those people, ask all sorts of questions, and share interesting parts of the work!

Write Open Source is going to be a behind-the-scenes podcast for and about the technical writers and other experts who document open-source software. We hear about special projects, overcoming challenges, and learning new methods.

To create the podcast, I chose anchor.fm from Spotify. It simplifies the workflow of creating, producing, and distributing your podcast to all the major platforms, for free, from one simple mobile app.

I’m not sure I’ll publish regularly: I tend to “go silent” as I approach major work deadlines. On the upside, my interest in and involvement with the subject is evergreen, so I don’t expect to “podfade” out of existence. The main question in my mind is whether I’ll be able to get other tech writers, who are notoriously introverted, to speak on the record about their work. I have a feeling the audio format will make this easier than, say, trying to make a video series on the same topic. We’ll see how it goes.

Disabled Parents and Starting a Business: A Few Essential Tips

I’m publishing the following post on behalf of Ed Carter, a retired financial planner and the founder of ablefutures.org. Ed offer tools, original articles, and other resources that will provide helpful financial information to members of the disabled community.  Ed says, “Many people are unaware of just how many options they have when it comes to financial assistance and planning, so it’s an honor to offer my experience and change people’s lives for the better.”

One in four American adults has a disability. Many of those with disabilities are parents who need a reliable income source despite having work restrictions. One option many disabled parents turn to is starting their own business. While the idea of starting a small business may seem daunting at first, using the tips below can help you get your new endeavor up and running.

Look for Grants

There are various grants and other funding opportunities available for disabled people. However, these funding sources may change quickly because they’re often offered on a first-come, first-served basis and close when funds are no longer available. You can keep up to date with current grant information by regularly checking the following websites:

You can also apply for a small business loan if grant funding isn’t enough. There are several types of loans designed for small businesses.

Start an LLC

Starting an LLC is an excellent choice for disabled parents looking to get their own business up and running. LLC stands for limited liability company, and it’s one way you can register your business. An LLC offers multiple benefits, including:

  • Greater flexibility when compared to alternatives
  • Limited personal liability
  • Tax advantages
  • Less paperwork
  • Increased credibility

Using a lawyer to form your LLC can be costly. You can save money by filing the paperwork yourself or using Zenbusiness, a formation service. Since each state has its own regulations on forming an LLC, it’s essential to research your area’s specific laws ahead of time.

Understand How to Hire In-House Staff

Hiring your first few employees can seem like an overwhelming task. The most important thing to understand is that you shouldn’t feel pressured to hire quickly. It’s worth waiting for the right employee, even if it takes weeks or months to fill the position. To ensure someone is the right fit, ask the following questions during the interview process to get a feel for each candidate:

  • How many years of experience do you have in this field?
  • Why do you want this job?
  • What are your greatest strengths?
  • What is your greatest weakness?
  • Do you have any certifications, degrees, or on-the-job training that applies to this position?

You should also ask questions that apply to your specific industry and the available position during the interview process. At the end of every interview, ask if the candidate has any questions for you. Generally, you want someone to ask at least one question. This shows they’re interested in learning about the position and your business.

Outsource Where Applicable

It isn’t always financially prudent to hire an in-house team member, but you may not have the necessary skills to perform a task your business requires. At times like these, outsourcing becomes the most viable option. To choose whether to outsource or hire an in-house team member, ask yourself two essential questions:

  • Does this position have 20+ hours of steady work available each week?
  • Does outsourcing or hiring in-house make more financial sense?

Applying These Tips

Starting a business is an excellent option for disabled parents. Applying the above tips can make the process smoother by helping you find funding, choose a business structure, understand how to hire staff, and decide when outsourcing makes more sense. 

Image via Pexels

Command ‘brew’ not found

Let me guess: you just installed Homebrew on your Linux system because you were going to use it to install some other software. Instead, when you tried to install the software, you got something like this:

$ brew install <software-name>
Command 'brew' not found

This response means the command can’t find the brew application binary. This happened because the Homebrew installation omits an essential step: adding the path of the brew binary to the Linux $PATH variable.

To fix this, you must add an instruction to your ~/.profile or ~/.bashrc configuration file that adds the path of the brew binary to the Linux $PATH variable.

So, what is the path of the brew binary?

Earlier, when you installed Homebrew, the output showed the location of the brew binary. Optional: Scroll up through your command history to see if it is still visible. For example:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
==> Checking for `sudo` access (which may request your password).
==> This script will install:
/home/linuxbrew/.linuxbrew/bin/brew
/home/linuxbrew/.linuxbrew/share/doc/homebrew
/home/linuxbrew/.linuxbrew/share/man/man1/brew.1
/home/linuxbrew/.linuxbrew/share/zsh/site-functions/_brew
/home/linuxbrew/.linuxbrew/etc/bash_completion.d/brew
/home/linuxbrew/.linuxbrew/Homebrew

Press RETURN to continue or any other key to abort

If you have root privileges, brew installed to /home/linuxbrew/.linuxbrew/bin/brew. Otherwise, if you don’t have root privileges, it installed to ~/.linuxbrew/bin/brew.

In any case, the following commands (which I found slightly buried in the Homebrew documentation) will sort this out. They find which path has the brew binary and adds it to your .profile configuration file. Paste the following commands in your terminal.

test -d ~/.linuxbrew && eval $(~/.linuxbrew/bin/brew shellenv)
test -d /home/linuxbrew/.linuxbrew && eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)
test -r ~/.bash_profile && echo "eval \$($(brew --prefix)/bin/brew shellenv)" >>~/.bash_profile
echo "eval \$($(brew --prefix)/bin/brew shellenv)" >>~/.profile

After this, restart your terminal. When you do this, .profile adds the path to your system’s $PATH variable.

Now, verify that the brew command works by using it to install some software. Please let me know how this works for you. If not, I’ll try adding some troubleshooting steps.

Now…why was I installing Homebrew? Ah yes, I installed it so I could install the GitHub CLI:

rolfedh@rolfedh-HP-Z2-Mini-G3-Workstation:~$ brew install gh
==> Homebrew is run entirely by unpaid volunteers. Please consider donating:
  https://github.com/Homebrew/brew#donations
==> Auto-updated Homebrew!
Updated 1 tap (homebrew/core).
==> Updated Formulae
Updated 48 formulae.
Updating Homebrew...

==> Downloading https://ghcr.io/v2/linuxbrew/core/gh/manifests/2.0.0
######################################################################## 100.0%
==> Downloading https://ghcr.io/v2/linuxbrew/core/gh/blobs/sha256:ac34664fe701dc
==> Downloading from https://pkg-containers.githubusercontent.com/ghcr1/blobs/sh
######################################################################## 100.0%
==> Pouring gh--2.0.0.x86_64_linux.bottle.tar.gz
==> Caveats
Bash completion has been installed to:
  /home/linuxbrew/.linuxbrew/etc/bash_completion.d
==> Summary
🍺  /home/linuxbrew/.linuxbrew/Cellar/gh/2.0.0: 97 files, 27.8MB
rolfedh@rolfedh-HP-Z2-Mini-G3-Workstation:~$

minikube ugh! microk8s yay!

I just spent hours trying to get minikube up and running on Linux Mint 20.2 Cinnamon. Endless installation and dependency problems (even though I’ve installed it on other platforms in the past).

Finally, I installed microk8s using snap. No problem. 

rolfedh@rolfedh-HP-Z2-Mini-G3-Workstation:~$ microk8s status
microk8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
addons:
  enabled:
    dashboard            # The Kubernetes dashboard
    dns                  # CoreDNS
    ha-cluster           # Configure high availability on the current node
    istio                # Core Istio service mesh services
    knative              # The Knative framework on Kubernetes.
    metrics-server       # K8s Metrics Server for API access to service metrics
    registry             # Private image registry exposed on localhost:32000
    storage              # Storage class; allocates storage from host directory
  disabled:
    ambassador           # Ambassador API Gateway and Ingress
    cilium               # SDN, fast with full network policy
    fluentd              # Elasticsearch-Fluentd-Kibana logging and monitoring
    gpu                  # Automatic enablement of Nvidia CUDA
    helm                 # Helm 2 - the package manager for Kubernetes
    helm3                # Helm 3 - Kubernetes package manager
    host-access          # Allow Pods connecting to Host services smoothly
    ingress              # Ingress controller for external access
    jaeger               # Kubernetes Jaeger operator with its simple config
    keda                 # Kubernetes-based Event Driven Autoscaling
    kubeflow             # Kubeflow for easy ML deployments
    linkerd              # Linkerd is a service mesh for Kubernetes and other frameworks
    metallb              # Loadbalancer for your Kubernetes cluster
    multus               # Multus CNI enables attaching multiple network interfaces to pods
    openebs              # OpenEBS is the open-source storage solution for Kubernetes
    openfaas             # openfaas serverless framework
    portainer            # Portainer UI for your Kubernetes cluster
    prometheus           # Prometheus operator for monitoring and logging
    rbac                 # Role-Based Access Control for authorisation
    traefik              # traefik Ingress controller for external access

My favorite Kubernetes books

Note: I did not include any affiliate links in this post.

Nigel Poulton’s Mastering Kubernetes bundle on Leanpub, $12.99.

A couple of years ago, I bought the ebook and audiobook versions of Nigel’s The Kubernetes Book. I became a huge fan of his humor and ability to deliver key information about complex topics.

This weekend, I found an interview with Nigel on the Leanpub Frontmatter podcast. I enjoyed hearing about how his father saved up for his first computer, how he got started in tech, how he started developing courses and writing books, and how he and his family are doing currently.

Inspired by all that, I decided to look for his current books on Leanpub and found the aforementioned Mastering Kubernetes bundle, which contains the 2021 editions of The Kubernetes Book and Quick Start Kubernetes.

You might ask, why pay for a book about Kubernetes, which already has comprehensive free well-written documentation? Aside from liking the guy, I bought Nigel’s books because he does a great job of summarizing and helping me retain the key information. His work saves me countless hours of reading. He doesn’t just present dry facts, he shares meaningful insights and opinions about the platform.

(Nigel, if you’re reading this post, skip the next sentence because I don’t want you to raise your prices.) If reading his books saves me only 15 minutes and increases my mastery of Kubernetes, they are worth far more than the small price I paid for them.

I also like supporting Leanpub. Authors earn 80% royalties on their books and courses. The platform enables authors to set sliding scale prices for their works. And the platform encourages authors to publish early and publish often — to better gauge their readers’ interests and needs and therefore deliver information that has more value.