This is a few days late, but wanted to write it anyway to keep the discipline and routine going.
I subscribe to several really high-quality newsletters and one post last week was of immense use. It was Exactly What to Say in Code Reviews by Jordan Cutler.
Getting the tone, content, and style right in code reviews is a significant part of collaborating in engineering teams. It involves many trial-and-error iterations, a lot of self-reflection, and an understanding of the culture of the team you’re on.
So, Jordan’s post was like getting a well-constructed, time-tested, and solid toolbox for Christmas, for this part of engineering work.
I applied some of the principles while doing code reviews last week. I actually brought up the post and put it side-by-side with the pull requests.
Judging by my coworkers’ replies and comments, I knew that I had carried out some effective strategies.
Thank you, Jordan!
Tag: GitHub
Addressing GitHub’s Vulnerability Warning in Your Code Repository
If you’re not averse through trawling through threads on GitHub issues, this is a concise list on how to address GitHub’s vulnerability warnings in your code repository. You will see a yellow-coloured warning box if one has been detected in your package-lock.json file.
(Courtesy of GitHub)
Assuming that the offending package is hoek:
$ npm ls hoek- Examine the output.
- Look at the package listed at the top of the tree –
json-serverin this case.Hoekis a subdependency to it viarequest, so the latest (or, updated) version of request would solve this issue. - I looked at the releases page for json-server and updated my
package.json`to the latest version of the package. $ npm install- If you run the first command again, you either will see the updated version of hoek or it won’t show up at all. The latter case means that it was dropped in the latest version of
json-server.
There you go! May it save someone hours of pain and Googling…
Approaching Documentation
One of my goals at work for the past month has teen driving efforts to improve our internal documentation for front-end developers. It would have been easier undoubtedly to just rant about it at meetings and talk about grandiose projects. I chose rather to do something about it in my own work.
- Pull requests. I used to just put a descriptive title and leave the description empty, sometimes linking to the original issue. A call-to-action came from my coworker, who asked me for a brief summary of changes so that it’s easier for him to understand what he was about to review. So, I put in some screen shots of any UI/UX changes, a few lines about background, something about the context for the pull request, and finally a short list of the main changes. In the last couple of weeks, I’ve started also adding links to any relevant documentation I wrote, such as backend API endpoints or anything in our product wiki.
- Internal documentation. We use a popular open-source system to house our internal front-end documentation. So, I’ve made it a part of my workflow to document any backend API endpoints in our system. That way, some developer won’t curse my name and the day I discovered programming when they have to maintain or debug my code.
- How-tos and repo documentation. Taking my coworker’s request further, I expanded any developer documentation that lives in the repository. This is usually either how to get started or how to implement a new feature. The effort spent on this (and
README.mdin tow) will hopefully mean that other developers will find it easier to get going with the codebase.
I actually like writing documentation!
