91 lines
7.1 KiB
Plaintext
91 lines
7.1 KiB
Plaintext
<h2>Automating the Repetetive while also Learning a Bit More about My Editor</h2>
|
||
<p>In <time datetime="2021-10-04" title="2021-10-04">October</time> I joined Forem as the lead engineer for the content experience team. I’ve been contributing to open source software for 9 years; Hello <a href="https://samvera.org">Samvera.org</a>; I miss you but I promise I’m in a good place.</p>
|
||
<p>Coming from one open source community to another, I brought with me different workflows. I favor writing verbose commit messages. I like to use that as the text for my pull requests. The benefits are that commit messages travel with the code-base. I can use <code>git annotate</code> to help me understand the situation around a chunk of code.</p>
|
||
<p>But, in an open source community with over 600 contributors, the commit message as pull request strategy is inadequate. We could use <a href="https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks">git hooks</a> to provide commit message templating, but that’s not enough for conversations around the pull request.</p>
|
||
<p>Forem provides a <a href="https://github.com/forem/forem/blob/main/.github/PULL_REQUEST_TEMPLATE.md">pull request template</a> to guide contributors through all of the considerations that go into the pull request review and acceptance.</p>
|
||
<p>The template provides a nice pre-amble comment to help new contributors. Then provides clear sections and instructions for a contributor to fill out:</p>
|
||
<ul>
|
||
<li>What type of Pull Request</li>
|
||
<li>Description</li>
|
||
<li>Related Tasks & Documents</li>
|
||
<li>QA Instructions, Screenshots, and Recordings</li>
|
||
<li>Accessibility Concerns</li>
|
||
<li>Added/updated Tests</li>
|
||
<li>How will this change be communicated? (A Forem Core Team only section)</li>
|
||
<li>Any post deployment tasks to complete</li>
|
||
<li>A GIF that Expresses How You Feel About this Contribution</li>
|
||
</ul>
|
||
<p>As a new contributor to Forem, I love this guidance. And as I began reviewing other pull requests, I appreciated the structure even more.</p>
|
||
<h2 id="my-current-pull-request-workflow">My Current Pull Request Workflow</h2>
|
||
<p>When I’m working on the code, I continue to write verbose commit messages. Then, when I’m ready, I push up my branch and push the button to create a pull request for the branch.</p>
|
||
<p>By default, Github prepends the last commit message to the text of the pull request template. I focus my browser into that text area and use the <a href="https://github.com/dmgerman/editWithEmacs.spoon">editWithEmacs.spoon</a> to copy that text and paste it into a new Emacs buffer on my machine.</p>
|
||
<p>In that Emacs buffer, I then go about editing the pull request text.</p>
|
||
<p>When I’m done, I type <kbd>Ctrl</kbd>+<kbd>c</kbd> then <kbd>Ctrl</kbd>+<kbd>c</kbd> (e.g., <code>C-c C-c</code> in Emacs parlance) to copy the text from my Emacs buffer and paste it back into the browser’s text area. <small><a href="http://magit.vc">Magit</a> and <a href="http://orgmode.org">Org Mode</a> use that key combination for confirmation of commands.</small></p>
|
||
<p>And I submit my pull request.</p>
|
||
<h3 id="automating-my-workflow">Automating My Workflow</h3>
|
||
<p>Once I started editing these pull requests in Emacs, I started to see the clean-up work that I was regularly doing before I started filling out the checkboxes. And because I was now in my text editor, I chose to write a script to do that clean-up.</p>
|
||
<p>Without reading the elisp code, it:</p>
|
||
<ul>
|
||
<li>Removes the comment preamble</li>
|
||
<li>It adds the last commit message as the description</li>
|
||
<li>It tidies up the comments of two sections</li>
|
||
</ul>
|
||
<p>Below is the lisp code to do the tidying up:</p>
|
||
<pre><code class="language-lisp">(defun jnf/forem-tidy-pull-request ()
|
||
"Perform some quick tidying of the Forem PR template."
|
||
(interactive)
|
||
;; Start from the beginning.
|
||
(beginning-of-buffer)
|
||
|
||
;; The text before the first HTML/Markdown
|
||
;; comments is the commit message. Cut that
|
||
;; text...
|
||
(search-forward "<!--")
|
||
(kill-region 1 (- (point) 4))
|
||
|
||
;; ...and paste it inside the description
|
||
;; section.
|
||
(replace-string
|
||
"## Description\n\n"
|
||
(concat "## Description\n\n"
|
||
(format "%s" (car kill-ring))))
|
||
|
||
;; We've moved point (e.g., the cursor) so let's
|
||
;; jump back to the beginning of the buffer.
|
||
(beginning-of-buffer)
|
||
|
||
;; Remove HTML/Markdown comments
|
||
(replace-regexp
|
||
"\\(\n\\)*<!--\\(.\\|\n\\)*-->\\(\n\\)*"
|
||
"")
|
||
|
||
;; Clean out the comments for QA instructions;
|
||
;; I'll write them, but the notes are
|
||
;; unnecessary.
|
||
(replace-regexp
|
||
"QA Instructions, Screenshots, Recordings\\([^#]\\)*"
|
||
"QA Instructions, Screenshots, Recordings\n\n")
|
||
|
||
;; Clean out accessibility concerns; I'll write
|
||
;; them, but the notes are unnecessary.
|
||
(replace-regexp
|
||
"UI accessibility concerns?\\([^#]\\)*"
|
||
"UI accessibility concerns?\n\n"))
|
||
</code></pre>
|
||
<p>Then comes the keyboard bindings to make this easier.</p>
|
||
<p>When copying from browser to Emacs, the <code>editWithEmacs.spoon</code> toggles on the <code>hammerspoon-edit-minor-mode</code> for the buffer. <a href="https://github.com/dmgerman/editWithEmacs.spoon/blob/45d44f4ecbeedd0959ac07c2a41d30bd2633ddc1/hammerspoon.el#L55-L64">See the code for those details</a>. The following code adds a new key binding <kbd>Ctrl</kbd>+<kbd>c</kbd> then <kbd>t</kbd> to the keyboard mappings.</p>
|
||
<pre><code class="language-lisp">(define-key
|
||
hammerspoon-edit-minor-map
|
||
(kbd "C-c t")
|
||
#'jnf/forem-tidy-pull-request)
|
||
</code></pre>
|
||
<p>Kind of nice. Load the content into an Emacs buffer, type <kbd>Ctrl</kbd>+<kbd>c</kbd> then <kbd>t</kbd> and I’m a few steps closer to completing my pull request.</p>
|
||
<h3 id="what-remains">What remains?</h3>
|
||
<p>I wrote a script to <a href="https://github.com/ndlib/commandline-tools/blob/cd09d035cf00ff428d5a5a9f6fa986343597fa54/bin/build-pull-request-message">build a pull request message</a> from commit messages. <small>Note, at my previous employer they chose to keep using—and keep choosing to use—the branch name <code>master</code> hence the code defaults to that.</small></p>
|
||
<p>I would like to better incorprate that conceptual script into my workflow.</p>
|
||
<p>And if I’m feeling up for the challenge, I’ll grab any Github links from the commit messages and add those to the related tasks and documents.</p>
|
||
<h2 id="conclusion">Conclusion</h2>
|
||
<p>Since joining Forem, I’ve issued 32 pull requests. And as I started doing this task more, I started wondering, “How might I tweak my tooling to address some repetetive tasks?”</p>
|
||
<p>I let that question linger as I wrote several pull request messages in Emacs. And then, with a bit of time, I chose to spend a bit of time writing the above script. I don’t know how many pull requests I’ll need to write to “make up” for the time spent on the script.</p>
|
||
<p>But that is a lesser concern. I’m more concerned with getting comfortable understanding the interplay of the various systems I use and how I can mold them to assist in the tasks at hand.</p>
|
||
<p>When I start to create a pull request, I can quickly run the clean up task so that I can then focus on writing the pull request. In other words, I automated away a “distraction” so I could stay closer to the area of focus.</p> |