To get updates when I post new content here, please click Follow in the lower right corner.
Note: I use Jetpack to handle followers/subscribers. Jetpack doesn’t allow anyone to export contact this information, so you don’t have to worry about anyone misusing it.
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?
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.
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 firstname.lastname@example.org: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
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:
Diagrams help your readers understand. Chris Metz gives "A brief demonstration of Mermaid.js" – Write Open Source
- Diagrams help your readers understand. Chris Metz gives "A brief demonstration of Mermaid.js"
- Jim Angel, Infrastructure Cloud Consultant at Google, on how NOT getting a $1/hr raise launched his tech career
- Tim Bannister on contributing to the Kubernetes.io documentation
- Mike McKiernan at Red Hat tells us about using Git Commit to automate adding metadata to his content files
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 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.
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
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
~/.bashrc configuration file that adds the path of the brew binary to the Linux
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
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
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:~$