In addition to eating my own dogfood, I started finding and talking to experts and stakeholders.
For experts, I went to folks inside and outside Red Hat. At Red Hat, I talked to Fabrice Flore-Thebault and Yana Hontyk. Last year, they presented on using Vale with their documentation sets: Eclipse Che and CodeReady Workspaces. I talked to them about their workflow, the issues they had fixed, and results.
Outside Red Hat, I pulled together an unconference session at Write the Docs Portland conference with Mike Jang from GitLab and Jodie Putrino at NGINX. They spoke about their differing approaches to rolling it out at their organizations. Lynette Miles at TAG1 Consulting also contributed.
For stakeholders:
I talked with my manager, who was supportive.
I arranged a meeting for Yana and Fabrice to present their work to a small group of writers, content strategists, and managers who had expressed an interest in rolling out Vale. The group expressed a lot of interest, and we agreed there should be some follow-up actions, like additional pilot programs.
As an aside, Fabrice and Yana’s presentation included the following impressive graph. It shows how they iterated on both the documentation and Vale style rules to achieve nearly zero errors, both real errors and false positives, over the course of almost two years:
To prepare for the follow-up, I have created a repo that contains a preliminary set of Vale config files and styles: https://github.com/rolfedh/studious-fortnight (definitely a work-in-progress).
I’ve heard complaints about the peer review process at a variety of organizations where I’ve seen it in use. To simplify, they sound like this:
Writers: When I fix a set of issues and resubmit the PR, the reviewer(s) come up with a new set of issues.
Reviewers: I keep flagging the same set of stupid !%$%*$# issues.
Everyone: Ugh. This takes too much time and effort.
In some cases, the peer review process can be demoralizing and spark interpersonal conflicts.
Looking for a solution to this issue, I turned to Vale, a style linter that has been gained traction at a variety of organizations, such as GitLab, NGINX, and elsewhere. At Red Hat, a couple of doc projects have been using it for over a year and there seems to be growing interest in expanding its use.
My first step was to start using Vale to get hand-on experience using it: eat your own dog food, etc. In my enthusiasm, I popped $57 for a Vale Server license.
Installing Vale Server wasn’t hard. Finding and configuring the pair of plugins to make it work with my Atom editor was a little confusing. Setting up the single plugin for VS Code was easy.
I installed all the built-in styles for Vale Server, but then had trouble applying them to my docs. Installation is not enough. One must also create a project in Vale Server and configure it to use the styles.
Overall, the process was a bit tricky enough that I realized rolling it out to a team of writers would require documented procedures, tutorial videos, and live support.
It’s also unclear whether my organization would commit to purchasing Vale Server licenses at first. So, I would need to figure out how to roll out Vale, the CLI tool, instead of Vale Server. To make the distinction clear, I’ll refer to Vale as Vale CLI from now on.
Vale CLI is simpler to install and configure than Vale Server. However, I believe Vale CLI alone doesn’t integrate with editors like Atom and VS Code. With Vale CLI, you get all your feedback by running the vale command against your file or files from the CLI. For example:
$ vale README.md
The output looks something like this:
Typical feedback from Vale CLI
In some ways, it’s less distracting to get with this command line feedback after you write a block of content. Vale Server highlights issues in your text editor when you save your current text. In other words, with Vale Server, the feedback is both more immediate and in some ways distracting. Six one way, half-dozen the other.
Every so often, I clean up old working branches I don’t need any more.
After I’ve written or revised content, and the pull request has been merged from my fork of the repo into the main branch of the organization’s repo, it’s time to get rid of the old working branches.
TLDR/Copy and paste
Here’s a summary of the commands for you to copy and paste.
cd <repo-directory>/
git checkout <main branch>
git fetch upstream <main branch>
git branch --merged
> Make sure the branch is dead
git branch -D <branch-name>
git push origin :<branch-name>
Verbose
Sections:
List the merged branches
Make sure the working branches are really dead
Delete the dead branches
List the merged branches
I start by listing the merged branches in my local repo:
$ cd openshift-docs/ # Change to the project/repo directory
$ git checkout main # Check out the main or master branchAlready on 'main'
Your branch is up to date with 'upstream/main'.
$ git fetch upstream main # Fetch information about branches from your upstream repo remote: Enumerating objects: 46, done.
remote: Counting objects: 100% (36/36), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 19 (delta 15), reused 12 (delta 10), pack-reused 0
Unpacking objects: 100% (19/19), 3.11 KiB | 176.00 KiB/s, done.
From github.com:openshift/openshift-docs
* branch main -> FETCH_HEAD
54901a001..b051f3c46 main -> upstream/main
$ git branch --merged # List local branches that are merged in the upstream repo
RHDEVDOCS-2465-replace-docker
RHDEVDOCS-2514
RHDEVDOCS-2609
RHDEVDOCS-2618
RHDEVDOCS-2740-rn
bz#1873372
* main
Make sure the working branches are really dead
Early on, when I start a new project, I use the ID of the Jira or GitHub issue to name the working branch and PRs. This makes it simple to know which issue, branch, and PR belong to each other.
When I’ve finished using a working branch, to make sure I don’t need it any more, I search my closed pull requests for the issue ID. I review the pull request to make sure that the PR that was merged into the main branch was also cherry-picked into all relevant release branches. I also look at the issue to make sure its state is “closed.”
When I’ve confirmed that a branch is not only merely dead, but really most sincerely dead, it’s time to…
Delete the dead branches
I return to my terminal and delete the branch by entering:
$ git branch -D <branch-name>
Then I push the deletion to origin by entering:
$ git push origin :<branch-name>
Notes
Many repos still use master as the name of their primary branch. In this post, I have changed the name to main and will continue to do so in future posts.
Please share your comments, questions, and suggestions for improving this post, below!
I am sitting in our car with the dog while my wife has gone into the food store wearing a mask to buy groceries. I’m experimenting today to see how well writing a blog post using voice-to-text on my phone works.
As far as I know, there aren’t any good inexpensive or free ways to do this on my Linux-based desktop computer, which I usually use for writing blog posts. But I find the voice-to-text feature that my phone has works extraordinarily well.
I’m sure there are similar options for users running Windows or Mac OS, but it doesn’t matter. This post isn’t about the availability of voice-to-text on different platforms.
So what I’m finding is that it works pretty well. All you have to do is spend a few minutes thinking through the purpose of the blog post. Then, you spend a few moments before each long sentence or paragraph thinking through what you want to say next. Then you narrate it.
Editing works the same way it does all the time, which is to say that you touch the screen where you want to insert text, or you select words that you want to delete.
I find that I tend to do a lot less editing this way because my spoken phrases tend to be very natural and clear.
To summarize, I find the process pretty natural and easy. It seems to go a lot faster than typing blog posts. I’ll try composing blog posts this way more often.
Verify that “Your branch is up to date with ‘upstream/enterprise-4.8’.”
git cherry-pick <commit hash>
Go to the pull request that has the merge failure (e.g., like this example). Copy the commit hash. In the terminal, replace <commit hash> with the real one. Enter the command.
Ignore “CONFLICT (content): Merge conflict in <path/filename>
In Atom editor (or whatever), manually resolve the merge conflict. Save and commit the changes as “Manual CP of RHDEVDOCS-<jira#> #<pr#>”.
git status
Confirm “Your branch is ahead of ‘upstream/enterprise-4.8’ by 1 commit.”
git push -f origin enterprise-4.8
Go to origin/enterprise-4.8 in GitHub and create the pull request with the following description.
https://issues.redhat.com/browse/RHDEVDOCS-2617
Previously merged as https://github.com/openshift/openshift-docs/pull/29491/files
[enterprise-4.8]
Copy the URL of this new PR and paste it to a comment in the Jira issue (e.g., in RHDEVDOCS-2617).
checklists serve the following functions.
Act as memory guide.
Ensure that all critical actions are taken.
Reduce variability between pilots.
Enhance coordination during high workload and stressful conditions.
Here’s the merge conflict message our merge master got when she tried to cherry pick my pull request (PR) to version 4.7 of the published OpenShift docs (lines , below).
openshift-cherrypick-robot commented 4 days ago •
@theythemself: #29573 failed to apply on top of branch "enterprise-4.7":
Applying: [RHDEVDOCS-2614](https://issues.redhat.com/browse/RHDEVDOCS-2614) Define ClusterLogForwarder compatability Matrix
Using index info to reconstruct a base tree...
M logging/cluster-logging-external.adoc
Falling back to patching base and 3-way merge...
Auto-merging logging/cluster-logging-external.adoc
CONFLICT (content): Merge conflict in logging/cluster-logging-external.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
Patch failed at 0001 [RHDEVDOCS-2614](https://issues.redhat.com/browse/RHDEVDOCS-2614) Define ClusterLogForwarder compatability Matrix
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".
Here, I start by deleting the enterprise-4.7 branch (line ) because it had a previous unmerged commit sitting at the top of the pile. (In the future, I think I’ll avoid this by creating a working branch off of the enterprise-4.7 branch.)
[memyself@memyself openshift-docs]$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'upstream/master'.
[memyself@memyself openshift-docs]$ git branch -D enterprise-4.7
Deleted branch enterprise-4.7 (was 803d05ddd).
Next, I create a new enterprise-4.7 branch that tracks Red Hat’s upstream repo (line). I don’t track my forked copy of the repo, origin, because it has that previous unmerged commit sitting at the top of the pile. (Again, there are other better ways to deal with that problem, I’m just sharing the one I used here.)
[memyself@memyself openshift-docs]$ git checkout --track upstream/enterprise-4.7
Branch 'enterprise-4.7' set up to track remote branch 'enterprise-4.7' from 'upstream'.
Switched to a new branch 'enterprise-4.7'
I fetch the latest changes from upstream and use status to verify that my branch is up to date.
[memyself@memyself openshift-docs]$ git fetch upstream
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 6 (delta 4), reused 5 (delta 4), pack-reused 0
Unpacking objects: 100% (6/6), 1.22 KiB | 1.22 MiB/s, done.
From github.com:openshift/openshift-docs
335951a8d..0f6dbceae enterprise-4.5 -> upstream/enterprise-4.5
[memyself@memyself openshift-docs]$ git status
On branch enterprise-4.7
Your branch is up to date with 'upstream/enterprise-4.7'.
nothing to commit, working tree clean
I go to the pull request with the failed cherry pick and copy the hash of the commit. I always squash commits so each pull request has only one commit.
I cherry pick that commit into the 4.7 branch. The merge conflict on line 5 is expected.
[memyself@memyself openshift-docs]$ git cherry-pick 3cad05d66d11c2d38a08322222f6c9dcbfc839ab
Auto-merging modules/olm-mirroring-package-manifest-catalog.adoc
Auto-merging modules/cluster-logging-deploy-console.adoc
Auto-merging modules/cluster-logging-deploy-cli.adoc
CONFLICT (content): Merge conflict in modules/cluster-logging-deploy-cli.adoc
error: could not apply 3cad05d66... RHDEVDOCS-2589 OpenShift Logging: Update any installation/upgrade specific information to use our new channels.
hint: after resolving the conflicts, mark the corrected paths
hint: with 'git add <paths>' or 'git rm <paths>'
hint: and commit the result with 'git commit'
I check the status.
[memyself@memyself openshift-docs]$ git status
On branch enterprise-4.7
Your branch is up to date with 'upstream/enterprise-4.7'.
You are currently cherry-picking commit 3cad05d66.
(all conflicts fixed: run "git cherry-pick --continue")
(use "git cherry-pick --skip" to skip this patch)
(use "git cherry-pick --abort" to cancel the cherry-pick operation)
Changes to be committed:
modified: logging/cluster-logging-exported-fields.adoc
modified: logging/cluster-logging-upgrading.adoc
modified: modules/cluster-logging-configuring-image-about.adoc
modified: modules/cluster-logging-deploy-cli.adoc
modified: modules/cluster-logging-deploy-console.adoc
modified: modules/cluster-logging-eventrouter-deploy.adoc
modified: modules/cluster-logging-log-store-status-comp.adoc
modified: modules/cluster-logging-updating-logging.adoc
modified: modules/cluster-logging-visualizer-kibana.adoc
modified: modules/olm-mirroring-package-manifest-catalog.adoc
In Atom editor (not shown here), I inspect the file that contains the conflict, modules/cluster-logging-deploy-cli.adoc. In it, I select the set of changes I want to keep. Then, I stage and commit the changes.
Back on the command line, I complete the cherry pick process.
I -f force push the changes to 4.7 to origin, which is my fork of the repo.
[memyself@memyself openshift-docs]$ git push -f origin enterprise-4.7
Enumerating objects: 27, done.
Counting objects: 100% (27/27), done.
Delta compression using up to 8 threads
Compressing objects: 100% (14/14), done.
Writing objects: 100% (14/14), 1.62 KiB | 1.62 MiB/s, done.
Total 14 (delta 13), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (13/13), completed with 13 local objects.
To github.com:rolfedh/openshift-docs.git
+ 803d05ddd...bcc5f087b enterprise-4.7 -> enterprise-4.7 (forced update)
Finally, on GitHub, in rolfedh/openshift-docs, I create the pull request to merge the commit into openshift:enterprise-4.5 from rolfedh:enterprise-4.5.
I’ll need to repeat this process and come up with a more complete set of screenshots.
This past month has been a hard one for me. My mother is in hospice care at an assisted-living home.
Along with waves of grief about my mother’s approaching death and guilt for not being a better son, I’ve been struggling with anger at “the system.” The people within this system are kind, ethical, caring, and professional. And yet, time and again, they perform functions that reveal a sort of death industrial complex that is bent on extracting money and minimizing care, even if it shortens your loved one’s life.
I don’t believe in burdening others with my hardships. Instead, I want to give you advice that will hopefully be useful if you find yourself in a similar situation.
When your loved ones are dying, and you’re struggling with emotions and making difficult decisions, realize that you don’t have to do it all on your own.
To the people around you, admit that you’re struggling. Where appropriate, share your feelings. Otherwise, when you need to be with your feelings, you can excuse yourself from situations.
Ask a loved one to help you with the logistical and administrative work; there are forms to sign, phone calls, and purchases such as sending Ensure protein drinks, toothbrushes, hairbrushes, gowns, and multivitamins to an assisted living facility.
Know what your parent’s or loved one’s rights are or ask the person helping you to know what’s covered and what isn’t by the insurer, medicare, and Medicaid. This information is critical for getting care, medications, and coverage.
Don’t sign or agree to anything upfront or verbally. Always require documents and ask for a day to review them before you answer or make a decision.
Update, 4/2/21: I’ve striken some words, above, that I think were too specific to the time and situation when I wrote them. I was upset by some issues with my mother’s care at that time and that statement was too general. I have very positive feelings about the nursing home where she is presently and the hospice care provider that’s looking after her.
