article
- Dash from Kapeli
- BetterTouchTool
- CodeRunner
- Numi
- The branch name begins with the kind of branch this is. In our case we work on a new feature for our application, so we call it “feature”.
- The second thing you might notice is, the
MIH-318part of the name. This comes from our project management software. This is the short title of the ticket that the branch belongs to. More on that later. - The last part is the name of the feature. This could also come from your project management software and be the long name of the ticket, or it could be a descriptive name of the feature you are building. Something like
new-user-login-formorintegrate-stripe-payment-provider. - What is changed?
- Why was the change necessary?
- How does the project / part of the code / microservice look after making your changes?
- Are there any side-effects of your change?
- Do you want to add any commentary about your changes? Perhaps link to Stack Overflow answers that helped you, or blog articles and books you referenced during development?
- Is there anything unclear with your changes? Perhaps you have a road-block that you need help with? Or you are uncertain how your changes interfere with another component? Ask about that. This is the place to do that.
- Check the code for linting errors and warnings.
- Run all automated tests, including long-running integration tests.
- Run static (and behavioral) code quality analysis.
- Deploy the feature branch to a test environment automatically.
- Inform the reviewers about the results of the above steps, through a comment on the PR, and post the url of the deployed test environment.
- Block or unblock the the PR from being able to be merged, depending on the results of the above steps.
-
I wrote this guide originally in ~2019. Most things still apply! ↩︎
Die Blase OpenAI wird platzen und Apple wird davon profitieren
Ich habe mal wieder etwas von Ed Zitron gelesen. Erneut zum Thema OpenAI. Laut Ed wird die Blase OpenAI und generative AI platzen, und Auswirkungen auf die ganze Tech Industrie haben. Entschuldige bitte den etwas reißerischen Titel.
Ich habe mit Hilfe von ChatGPT (wie meta 🫣) das Ganze mal hinterfragt und wollte kurz meine Schlüsse teilen. Und warum das gut für Apple 🍎 sein könnte.
Der Artikel von Ed lautet „OpenAI Is A Systemic Risk To The Tech Industry“.
Kurze Zusammenfassung, falls du das nicht lesen willst. Es ist recht lang.
OpenAI hat kürzlich eine Finanzierungsrunde über 40 Milliarden US-Dollar angekündigt, von denen bisher nur 10 Milliarden eingegangen sind. Die restlichen 30 Milliarden sollen bis Ende 2025 folgen, sind jedoch an Bedingungen geknüpft, darunter die Umwandlung von OpenAI in ein gewinnorientiertes Unternehmen. SoftBank plant, 20 Milliarden beizusteuern, allerdings teilweise durch Kredite finanziert, was die Stabilität der Zusagen infrage stellt.
Mit einem geschätzten Jahresumsatz von 4 Milliarden US-Dollar im Jahr 2024 wird OpenAI mit dem 75-Fachen seines Umsatzes bewertet – eine Bewertung, die Zitron als überzogen und spekulativ einstuft.
Außerdem stellt Ed noch dar, wie OpenAI jedes Jahr 40 Milliarden benötigt um überleben zu können. Und SoftBank, der Hauptinvestor muss sich schon sehr strecken, einmalig die 40Mrd. bereitzustellen. (Details dazu im Artikel).
Hier jetzt ChatGPTs Kommentar und Analyse.
Zitrons Analyse wirkt überspitzt, trifft aber in den Kernaussagen ins Schwarze:
• Kosten & Skalierung: Richtig: OpenAI hat hohe variable Kosten pro Nutzer (v. a. bei GPT-4) und ist nicht natürlich skalierbar. Die Monetarisierung über ChatGPT Plus reicht nicht aus, um die Betriebskosten zu decken.
• Finanzierungsrisiko: Korrekt: OpenAI hängt stark von externer Finanzierung (v. a. Microsoft) ab. Ohne diese Subventionen wäre das aktuelle Modell nicht tragfähig.
• Sicherheitsbedenken: Ernstzunehmend: Verkürzte Prüfphasen bei neuen Modellen wurden mehrfach intern kritisiert. Der Zielkonflikt zwischen „schnell liefern“ und „sicher entwickeln“ ist real.
• Systemische Gefahr: Etwas übertrieben: OpenAI ist wichtig, aber nicht alleiniger Pfeiler der KI-Branche. Es gibt Alternativen und Diversifizierung.Kurzfazit: Zitrons Analyse ist polemisch, aber inhaltlich weitgehend fundiert – besonders, was Wirtschaftlichkeit und Sicherheitsrisiken betrifft.
Spätestens Ende 2026 sollte sichtbar sein, dass die Blase platzt. Oder sie ist dann bereits geplatzt. Wir werden es sehen. Aus dem Artikel wird auch klar, warum es eigentlich gar nicht anders gehen kann.
Wenn es so kommt, wie beschrieben, implodieren alle generativen AI Anbieter, wie OpenAI, Anthropic etc. Um dann weiterhin AI nutzen zu können, muss man also selbst AI betreiben können. Das würde heißen, man hat sein eigenes Datencenter, mietet sich Kapazität bei AWS oder Azure oder nutzt andere Möglichkeiten. Für mich heißt das, dass das Betreiben von AI lokal auf dem eigenen Rechner, nur noch wichtiger wird. Und dafür machen sich Apple Computer mit dem Apple Silicon Chips wirklich fantastisch. Apple ist zwar zu blöde Siri und ihre eigene Apple Intelligence richtig hinzubekommen, aber LLMs etc laufen mit Hilfe von Ollama ziemlich gut. Wenn die Tools die man nutzt, also darauf optimiert werden, dann wäre das ein Gewinn für uns alle. Viel viel viel Energiebedarf in den Rechenzentren würde eingespart werden können. Milliarden an Kosten für den Betrieb würde nicht mehr benötigt werden.
Was ich noch nicht weiß/verstehe/sehe: Wie die Weiterentwicklung der AI Lösungen laufen wird. Ich habe Schwierigkeiten mir vorzustellen, dass nach dem Platzen der Blase AI komplett weggeht. Unter anderem, wie eben beschrieben. Aber die Weiterentwicklung der Modelle wird fortgeführt werden.
Vermutlich werden die Chinesen am Meisten davon profitieren, wenn OpenAI hops geht, da sie wirtschaftlich nicht damit verbandelt sind—anders als die meisten nicht chinesischen AI Player.
Tumblr ist zurück, dank GenZ
Ich habe neulich mal geschaut, aber mein alter Tumblr Blog ist weg. Habe ich vermutlich gelöscht.
Ich erinnere mich, dass es da mal eine Kontroverse(?) gab oder so. In dem Zuge hatte ich dann den Account geschlossen und gelöscht, meine ich mich zu erinnern. Jetzt scheint Tumblr wieder vieles richtig zu machen.
Aber ich hab nicht genau nachgeschaut…
Neue Automation für um Websites als Draft-Posts zu Erstellen
Eine neue Automation für iOS ermöglicht es, schnell Entwürfe für Beiträge in Micro.blog zu erstellen.
Celebrating 19 years of writing on the internet
Thanks to the Wayback Machine I was able to find my first official blog post ever, from January 2006. The site is still online, at blogspot.com. I am very surprised by that.
I also learned, that I registered my first url (holgerfrohloff.de) in 2004. The first entry on the Wayback Machine is from February 19th 2007.
That makes this year the 20th year that I write on the internet. 🎉
(When navigating through the archives you can even access two songs that I recorded back then. While it was “nice” to listen to them again, I am not sad that they officially disappeared from the internet. But hey, thanks for the memories Wayback Machine.
Fun with creating LeaderKey actions
The author streamlined accessing their video call tool in Safari by using a keyboard shortcut instead of the mouse.
Keep your hope
Despite feeling overwhelmed by global crises, it’s important to recognize that we still have the power to take meaningful action within our own sphere of control.
More on AI. And fun with Jenny Lawson.
I just read an article from Jenny Lawson about how using AI is going very strong for her: No, I do not want AI to “polish” me.
But after I added the update gmail was like, “YOU’RE STILL DOING IT WRONG, IDIOT?” and the polish thing came up again and I was like, “Are you trying to AI fix a paragraph where I say how much I don’t want AI to fix shit?” And turns out, yeah, that exactly what it meant because it gave me this
I will not (hopefully!) write that much about AI in the future but yeah. It was too good to not share with you. Also: I mentioned recently how I sometimes use AI but didn’t give an example. So here is one. I like to use LLMs to rewrite my English sentences in a more idiomatic way. I use this mostly for writing where it’s important for me the reader has little option to mis-interpret my words. Because they might be bad English.
Found via @manton: www.manton.org/2025/01/2…
How I created a “On this day” feature in Obsidian for my journaling
The author describes their process of journaling in Obsidian, including importing past entries from DayOne and creating a dynamic “On This Day” feature using the Dataview plugin.
Eine typische Siri Situation 🤦
Leonie verlässt das Bad, geht in ihr Zimmer und sagt in ihr Zimmer hinein: „Hey Siri, weiter!“ Daraufhin antwortet Siri im Bad: „Wiedergabe hier fortsetzen oder in Leos Zimmer?“ Ich antworte, im Bad stehend: „In Leos Zimmer“ Darauf Siri: „Ich kann den Lautsprecher nicht finden.“ 🤦
New to me backup solution restic
I found the link to a new backup software that looked interesting.
I used to use Arq which costs money. When I was runnning my business and was self-employed it was a sensible cost to pay. Now that I am no longer self-employed I’d like to cut costs. Once Arq will ask to renew my license I’ll switch.
Posting this here for you as much as for me so I can find it again later. 😉
Restic is a modern backup program that can back up your files:
The brightest flame burns quickest
Maybe the answer is simpler than I think. Maybe I should just keep things simple. If I like my coffee the way it tastes, that should be enough. If I enjoy playing the guitar songs I love, there’s no need to dig into the theory behind them. And when I write on my blog daily or a few times a week, that’s enough too. There’s no need to turn a hobby into something bigger. It’s fine as it is — an enjoyable way to spend time. Trying to grow it into something more only leads to destruction.
I feel you, Yordi. I’ve been there. And I am not sure I am not still there. I always wanted to do things “right”. It’s actually a mantra of mine: “If something is worth doing, it’s worth doing it right.”
But that quickly leads to burnout and boredom. Unless you find a way to do things in moderation. Recently I picked up singing. And I do that maybe once or twice per week. And I enjoy it tremendously. Now I started playing piano again, and mostly re-learning it. And building on the little that I already knew. And I specifically set me the goal of not playing more than once or twice a week. Not daily or anything like that. Because then I know that I would hate it soon.
So yes, my last blog post was a few days ago. I don’t need to write daily. Let others do that. 🫶
Some small thoughts on the Middle East
This is a very personal, moving piece by @jsonbecker.
It’s surreal to see your cousin in a Washington Post video. It’s worse when the reason she’s being interviewed is because of her experience living in a community in Israel that was overrun on October 7th.
It’s been over a decade since I’ve seen her.
I am 42 years old. The “conflict in the Middle East” was present on the news for as long as I can remember. When I was around 15 years old I had the chance to take part in a student exchange program and travel to Israel. We lived in Ashkelon, a small city very close to the Gaza strip. It must have been near the end of the 90s and I guess it was a bit more relaxed (don’t want to say peaceful…) back then. I was able to visit Jerusalem and Tel Aviv and I am still impressed by what I experienced. The magic, the food, the architecture and all of the history. I would love to go back there and see everything with my adult eyes and experience it with the knowledge and appreciation I have today. But I wouldn’t go there now, or previously. As a kid I didn’t understand why people couldn’t stop fighting and my understanding did not grow as an adult. The blind hate and it’s source in the people’s religions is one reason I do not like religion. I don’t think that the fighting will ever stop in my lifetime and that thought makes me very sad. I am glad, personally, that I do not have any relatives in that region. My situation is very different from Jason’s. Still I feel for him and how torn he has to feel. How frustrated and helpless.
Fedi(verse) is for losers? I don't care.
From where I sit, I don’t see that we have a strategy. Fedi is fine and all, but it doesn’t scare anyone. That’s not good enough. Twitter was always flawed but it was a great tool for activism and continues to be useful in some ways. Bluesky has some of that old-Twitter vibe, and perhaps it will supplant the original, in time; inshallah.
I wouldn’t count myself as part of the fediverse but I am. I don’t do Mastodon. It’s one of the reasons I use micro.blog to host my content right now. I don’t think that joining a mastodon instance is the right way. In my opinion the best way to share your thoughts is on your own personal website using your own domain name. A name that you control. And then use federation through protocols like ActivityPub to take part in the social circles. That way I don’t have to care about Mastodon or the fediverse.
We deceive ourselves as to what constitutes effective action, and we are deceived by billion dollar algorithms that understand our subconscious better than we do and feed our illusory sense of accomplishment through facilitating and encouraging such paltry (yet addicting) protests.
When I read the original article up top about “the fediverse is for losers” in my opinion it touches on this exact topic. The fediverse isn’t good for activism. You don’t use it to make the world better. You use it to complain about what others do (which is kind of what I am doing here right now 🙈). If you really want to make the world a better place, change routines in your daily live. Interact with people outside of your computer. Bring a smile on another person’s face. Show them you care.
Pinboard is dead. At least for me. Let me tell you how I bookmark in 2024.
Yesterday, I read an opinion about the bookmarking service pinboard.in. I am a user since 2010. In 2019 I paid ~$210 for a 10 year contract because I wanted to do my part to keep the service running and enable the founder to do his thing. Because I believed in his mission and the purpose of the service. Gordon made me aware that Pinboard might be over. There is a Hacker News thread for the linked article where alternatives are discussed, if you are interested. The thing is, I believe Gordon and others might be right. Roughly 1,5 years ago I tried to write a small application to interface with the Pinboard API. Unfortunately, the API didn’t work as expected. When I looked into it, I learned about a version 2 of that API that was supposed to be in development. The documentation to that API was insufficient and things didn’t work in any way like they were documented. When I reached out to the Pinboard founder I heard nothing back. The state of the API hasn’t changed at all since then. There were no updates.
The founder still writes on the web about things like lunar programs and moon landers with SpaceX and other political topics. He also gave entertaining talks on conferences during the last years. But he didn’t do what he was paid for. At least in my opinion. Sure, the basic website still works. And maybe that could be considered enough?
I have since stopped using the service. Bookmarking is an activity I not do as often anymore as before. If I want to have a website handy for later reading or watching, I use Omnivore. It’s an open-source solution that is free to use. Eventually you can even do self-hosting. I chose it because it works well and I can read and understand the code and tech stack. If they ever decide to discontinue the web app I can host it myself.
For saving website to reference later, which you could call bookmarking, I mostly use Obsidian. It’s my preferred solution for taking notes that I want to keep. Right now I have over 5.600 notes in there. A big part of those are my journal notes, which I imported from Day one.
To make saving websites quicker I wrote a small Alfred.app workflow that calls a Shortcut (from Apple shortcuts). If everything works out (it does most of the times!) a note is created in Obsidian.
I attached a screenshot of the note, because I don’t have a good way to share it with you otherwise right now. Those bookmarks land in a folder called /sites. I can add tags and link them to my notes, or references the bookmark in a note somewhere else. It doesn’t save a complete copy of the bookmark. So if the website disappears from the web, my bookmark would cease to work. Maybe that is something that I will add later. I am not sure yet.
So yeah, Pinboard is dead as far as I am concerned.
I canceled my SetApp subscription
Yesterday, I canceled my SetApp subscription. It’s around 110€ per year and I only use 3-4 apps from it. Did a quick i research and saw that I pay less for those apps if I buy them outright. And most of them will be supported for two years after purchase. Financially it’s a no-brainer and supports the developers even more. The apps I use?
I didn’t buy CodeRunner and Numi just now. The are both more expenssive (€20 and €35) and I don’t have a need for them currently.
A new Alfred workflow: Quickly open Merge Requests in GitLab
Synopsis
I created a workflow for Alfred so I can quickly open all the merge requests that are assigned to me. If the query “review” is added then all the merge requests where I am assigned as a reviewer are openend.
Background
I love to use Alfred to quickly to repetitive tasks on my computer. I use it to find the right emoji, modify text styles and text cases, convert images or units.
When at work, I also regularly have to open the overview pages on GitLab to see what status my merge requests have—or to quickly access them. I also want to navigate to the overview of the merge requests where I am assigned as a reviewer. Others might wait on my review or pushed updates.
All of that those lists exist as a bookmark in my browser. I can open them by clicking the bookmark. But then I have to decide whether I want to open a new tab or stay in the same tab I currently use. And I have to click with the mouse/touchpad.
This can be done quicker/easier: Open Alred (shortcut CMD-Space), type mrs and hit ENTER.
This opens the page where I can see the assigned merge requests.
If I want to access the MRs for review, I do the same but type mrs review. This overview is filtered for MRs where I haven’t approved yet.
Works wonderfully.
You can download the workflow from my GitHub repo
Vogelgesang während der Hunderunde
Heute morgen, während ich Milo spazieren führte, habe ich wieder Vögel bestimmt. Ich bin auf die App durch @Buddenbohm@fnordon.de aufmerksam geworden. Gerade bei uns am Kanal waren schön viele Vögel zu hören. Und ist es nicht schön? Sie singen so toll und ich kann endlich mal lernen, welcher Vogel wie klingt. Steigert nachhaltig die Naturverbundenheit. Und wer kann schon was gegen nachhaltig sagen.
Amsel und Gartenrotschwanz fand ich am Schönsten. Zaukönig und Buntspecht haben mich überrascht. Ich habe auch noch Elstern gehört, konnte sie aber nicht aufnehmen, weil der Hund da wieder Blödsinn machte in dem Moment.
Habe jetzt 10 Vögel in meiner Life List in der App. Mal sehen, welche ich auf der Nachmittagsrunde vernehmen werde.
The comprehensive guide to doing pull requests
This is a guide on what I consider the best way to do a pull request1. There are many ways to do this. I consider this to be the best way because of my experiences doing it like that with different teams. The results tell me that I am right. But first: What is a pull request?
What is a pull request, or: How should I integrate my changes with the code
To make any of this work, you need to be using a version control hosting provider like GitHub, GitLab or Bitbucket. All of them provide this functionality, Bitbucket even provides it for Mercurial repositories. I use Git with GitHub and GitLab.
A pull request (from here on I’ll call it PR), sometimes also called Merge Request (in GitLab) is a way to integrate the changes you made to the repository (the code base) with the master branch (that’s the code that goes live to production). I will not go into using Git too much right here, there are other articles about that. If you need a refresher on Git and branching, please come back after reading these articles.
So let’s assume you wrote your changes on your own branch, which I’ll call feature/MIH-318-my-feature-name. You already can see three things here:
Now it’s time to get these changes into testing (Staging environment or whatever you’d like to call it). Therefore you pushed your branch with the latest changes to your repository (origin) and open a new pull request to merge the changes into the master branch.
Why should you use PRs?
Using PRs gives you an incredible valueable feedback mechanism. This shares the responsibility of the work and makes sure you don’t break the application when things go live. This is because a PR is a great opportunity to catch bugs early on during the cycle. Catching bugs and errors earlier in the development cycle reduces the costs to fix them. After all, they didn’t interfere with other (new) code yet and are (hopefully) compartmentalized. PRs are also a good form of documentation, because of the description and discussion happening in a PR.
How do you do PRs?
Before opening a PR
I advocate for using before-commit hooks in Git. These hooks enable you to run custom scripts before commiting changes. There a quite a number of quality checks, if you ask me (and you kind-of do, since you are reading this! 😉), and almost all of them should be run before comitting your changes. I’ll mention the checks later on, as well.
Baseline measurements of a PR
One of the most important things to remember when doing PRs: Don’t let them get too big. A size I found to work well was around 400 lines changed. While this is no hard limit, going over it tends to incorporate too many changes at once. This makes the review harder for the reviewers.
Another thing not to lose track of, is the number of days a PR is open. You should review PRs as soon, as they are assigned to you, or when you are being mentioned in their description (or in comments). It is your duty not to let your team wait for too long on your feedback/review. If there are no major errors in the changes, a 400 lines feature should be reviewed and merged within 1–2 business days.
Who do you assign a PR to? Who should review?
This depends very much on your team structure and how you are organized. If it is possible, it would be great to get two people to review your changes. A healthy mix could be one person from your immediate team, and another one from a different team. This can have the benefit of a different perspective. The one from the outside-team probably doesn’t know too much about your feature and the specifics of your code. This forces you to be extra detailled when writing your description and documentation and they might not make some assumptions that you and your team take for granted. This situation needs to be handled carefully, you don’t want to get derailed by fundamental questions. But it could also prove to be beneficial to your feature, ymmv. It also increases knowledge across team boundaries, which I consider to be good practice.
If cross-team doesn’t work for you, try to get a more experienced (or same level as you) and a less experienced person from your team. While both reviewers will help you improve your result, the less experienced might get a chance to learn from reviewing your code.
In any case, @mention your reviewers in the description and (if possible in your software) assign the PR to the one you want to be responsible for merging.
What should you write in the description of a PR?
The first thing that you should write is a good title. This is the first thing that reviewers see, and it usually also goes into the emails they get about the PR. So make sure they understand what it is about. This is also a good place to let the reviewers know if you only want a review, without the goal of merging the PR. Perhaps you have an early draft of your feature, and want guidance on the general direction. You can do that by prefixing your title with something like
WIP: Integrate Stripe as payment provider
This WIP (work in progress) makes your intentions clear. If you are using GitHub, common practice is to use labels for that. So you could have a “Do not merge” label, or again a “WIP” label. I tend to always write it into the title as well, so people can’t miss it.
The next point to take care of is the description. This is where you should spent most of your time, when creating a PR. Consider writing about the following points:
If it makes sense, you should add screenshots of the before/after situation. If your changes contain animations or important visual effects, provide a gif or a short screencast of your changes.
Finally, make clear what you want the reviewers to look for, test or what they should comment on. If they follow this guide, they will look for more than that, but it is always appreciated to get a little guidance from the author of a PR.
Don’t forget to link/reference the issue/ticket in your management software that this feature/PR belongs to.
What role does CI/CD play in your PR?
My guideline for development workflows leans heavily on having a CI/CD server that orchestrates the whole workflow. CI/CD means continuous integration and continuous deployment. There is a lot to CI, and why and how you should do it. Look for multiple articles on that from me here. For the time being, you can get a wonderful introduction to the subject from another expert: Martin Fowler on his site.
Your CI server should do certain steps when a PR is opened. These include:
If you make your CI server report all linting errors, you free your developers to focus on the changes in the logic. Imagine the case where reviewers wants to check your PR, and the first thing they have to do is create lots and lots of comments about linting violations. Nobody will be able to focus on the really important changes and the discussions will grow very big. So let your robots (CI server) handle that for you.
How do you review a PR?
The first thing you should do is read the title and the description thoroughly. Your co-worker took her time and made sure you can get all the information you need out of the description. So read it carefully. Take a look at the screenshots and videos, so you get a sense of what it looks and feels like.
The next thing you should do? Check out the branch locally and run the tests. If the PR isn’t WIP anymore, the tests should all be green. On the CI server as well as on your machine. It is important to run the tests on your computer as well, because you could have a different setup with your database that could surface a hidden issue. Or you are using a different browser than your co-worker so you might see certain problems that are browser-specific. Looking at the feature on your computer provides the benefit of becoming more intimate with the changes and being able to look at them in a bigger context. The review interface on GitHub and GitLab often only show the changes and small amounts or neighouring lines. On your computer, you can see the whole glory. This is good for context.
When you find things that you want to comment on, please do this kindly. Be generous, everybody makes mistakes — even you. Write your comments as questions. This could look something like:
> I noticed you instantiate the Foo class inside the constructor. What were your reasons for doing that?
Even if you already know, that dependency injection would have been a better choice for this spot, help the other developer figure it out by asking questions. Do not tell them what to do or to change. Show them the direction, point them to places they could learn about how they could do it better, or explain why you think something might make more sense if they do it differently. The more context you provide and the more care you take to explain your questions and suggestions, the easier it will be to improve the code.
Remember: You are not your code.
Things to look for when reviewing a PR
There things that your linter won’t catch. These are long or unclear variable or function names. There might be code that is commented and can be deleted. Perhaps it was there from an earlier version of the code, as a draft. You could even find violations of the style guide, that the linter did not catch.
Perhaps your team writes documentation, like in classic docs or in a wiki. Was it updated correctly? Can you understand what was written? Is the ticket’s status updated and are all references to other issues or related changes present? Perhaps you can point the author to other changes in the code, or features or resources that are related to the thing you are reviewing (mailing-list threads, help-desk/service tickets, blog posts, articles or books)?
Take a look at the commits that are part of the PR. Do they conform to your commit-message guidelines? Do they make the feature’s history clear? What do you learn from scanning them? Are there any changes necessary?
Let me state again that the most important thing is to be polite, helpful and respectful of your co-workers. PRs should be a place to improve (the code and yourself) and to learn.
Best practices on doing pull requests
This section will deal with a few best practices that should increase the quality of your PRs as well as make your life easier, when using PRs.
Deploy a test build
I wrote about it before, but you should have your build server (or continuous integration server) deploy your branch-to-be-reviewed to a seperate, clean staging environment. This is where testers can have a look at your changes. This environment is a 100% copy for the production environment. The only thing missing is the real data from production (since that’s sensitive data). During the deployment the CI server will populate the environment’s database with seed data that is close to the data on production (and mirrors the size of production’s database).
You could name this a staging or remote test environment.
Document the lifecycle in your project management tool
It doesn’t matter whether you use JIRA, Trello, Asana or something else. As long as the tool integrates with your build environment and repository in a way, that you can easily jump between the ticket, the PR and any documentation on the wiki. The ticket needs to document the complete lifecycle from the creation of the new branch with every commit on it, to the PR and the CI server’s build results as well as the merge and deployment to the remote-test environment and, lastly, to production. You want to have a clear audit-trail easily accessible. This is not done to be able to point fingers, but to be able to understand why things are the way they are. Even 12 months later. That’s what your project management tool is responsible for.
Merging when everything is green and 👍
Merging PRs can be a story in itself. The most important thing is: Only merge when every reviewer gave you the thumbs-up and when the CI server indicates that there were no errors at all.
The merging should be done by the assigned reviewer. If there are multiple people responsible, you can talk about who should merge. It shouldn’t be the author of the PR. Allowing the author to merge her own changes leads to a bad practice where people merge to quickly, without a proper review. Other than that, it doesn’t matter whether the person merging is more or less senior than the author.
Where do you merge into, or: What’s the base branch?
The simplest strategy is to merge a feature branch (and most other branches) into the master branch. This is usually the branch that gets deployed.
It could be, that you follow a different dev methodology, like git-flow. If that is the case, you will probably merge into develop. So your base branch would be develop.
No matter what your base branch, note that:
Smaller features make merging easier
The less changes you want to merge, the easier it will be to review them. You should count on the fact that development of other features will continue while you are developing your feature branch. Those might have started earlier, or there were other branches that fixed bugs. In any case, your base branch will have moved on and evolved. It had a certain state when you branched off of it, but that state won’t be the same it is in right now. The longer you wait with your feature, the more work you’ll have to do — after you already thought you were done — when you want to merge your changes. This can be frustrating. You wouldn’t be the first one to introduce bugs at this point. Since the code has evolved, you are not yet that familiar with the new pieces. But you’ll have to make your code work with them. That’s where bugs are hiding.
The smaller the feature, the earlier you can merge and the less painful a process it will be.
Commit early and often with good commit messages
I wrote about it before: Let your commits be small and many. Your commits should follow the SRP (Single Responsibilty Principle). Your commit should change one thing. It might and could have side-effects. But it’s purpose it to change one thing. In your commit message’s subject (50 char length at max) you should succinctly describe what changes this commit introduces. Whenever you reach to the word “and”, you know your commit is too big.
A clean history of 2000 commits that are each tightly scoped and with clearly written commit messages is easier to understand and more helpful than 200 commits that each contain countless changes with minimal commit messages. Bad examples for commit messages, that are too often, are “fix”, “kill bug”, “add stripe” etc.
The commit message serves as your audit trail to your future self. Perhaps you have to do software development for a few years, but there will be a time where you scroll through your commit messages, searching for this one commit that helps you understand why a bug occurs, or why a library was rolled back to an older version. I’ve seen it with enough teams, that I really suggest you start improving your commit messages.
Do not squash your commits
This might be a contested opinion, but I am against sqashing commits. Please see the point above, but your commits paint a picture and tell a story. Squashing them loses this. Sure, the changes are there, but you are not able to identify how a change came to be.
There is one situation where squashing improves things: When you commit your code, without taking care to write good commit message or how to reduce your commit sizes. Then you squash your commits in the end and write a good, detailled commit message, that adheres to the before-mentioned best practices. This does increase the quality. The history, the how is still lost, but at least you can understand that one commit. That’s still better than many commits without proper messages.
There are people that do not like merge commits. I understand the reasoning, it seems to be an unnecessary commit. This is true, you can prevent this when rebasing your changes onto the base branch. This can be difficult if your repository changes very quickly.
If you do need to squash before merging (I don’t know or understand why, please tell me!) please only do it right before merging. Don’t do this when opening the PR. Your reviewers should be able to have a look at the history of the development of your branch.
Use templates to make your lives easier
Now that I explained why you need a well-written description and detailled commit messages, you might wonder how you can facilitate their creation.
I would propose you create templates.
We’ll start with commit message templates.
Git commit message template
Inside your project folder, you’ll find the .git folder. Open the .git/config file in your favorite text editor. Add the following lines:
[commit]
# can be local to your project or global
template = path/to/your/.gitmessage
It makes no sense, to create this for every project, so you can add this inside your global git configuration. On unix systems this can be found in
~/.gitconfig
You would add the same thing in there. I would propose you create a repository for your company or department where you store these templates. This makes it easier to update them for the whole team. Then you just clone the repository and link it correctly: template = path/to/cloned/repository/.gitmessage.
This is a basic template that you could tweak:
# 50-character subject line
#
# 72-character wrapped longer description. This should answer:
#
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# Include a link to the ticket, if any.
#
# Add co-authors if you worked on this code with others:
#
# Co-authored-by: Full Name <email@example.com>
# Co-authored-by: Full Name <email@example.com>
You would have this pasted into every commit message you create as a comment (the # signs denote comments in git messages). Then you never forget what to write about.
These templates work locally for every developer.
Pull request templates
If you use GitHub or GitLab you can create a template that will be used when somebody creates a PR in your repository. It works mostly the same as the git commit message template: Your template gets pasted into the description of the PR and you can use it as an aid to fill in the textbox. As far as I know, there is currently no way to require certain information to be filled out.
A way around that would be to have your CI server parse the PR description and complain on the PR if certain things are missing. This would mean that your developers need to be very disciplined in filling out the description, or else risk complaints by the CI server. If you would be interested in something like that, I will show how to do that in another article.
If you are using GitHub, you can find their description on how to use a pull request template on their help pages. GitLab offer a similar description, showing you how to create merge request templates for their service.
Both services let you use markdown to write your descriptions. There are some useful additions to Markdown available for you. You can put them to use in your template, so your developers gradually learn to use them properly. One of the biggest features is to create checkboxes in your description (or comments). This is done like this:
- [ ] Make logo more bigger
While your checkboxes won’t be mandatory to be checked for your pull request to be accepted, they do provide a nice visual cue about any open tasks.
Merge the pull request
I said it earlier already, the person merging the PR shouldn’t be the one who opened it. This helps to enforce the principle of four-eyes (or less, depending on your developers).
Finally the PR is merged and you can work on the next feature.
🎉
Another day, another stream
Yesterday I’ve streamed for another 2 hours. While I started with a “Just Chatting” segment, I quickly turned to programming again. Not least because I was only chatting with myself 😂.
Eventually I started with implementing an algorithm for “rolling weeks” in my chores app. Have a look to find out what that is about 😉
Spent 2.5hours streaming today
I spent 2.5hours streaming today. Last year I took up streaming and did around 2 hours in total. Today I just continued and didn’t stop until it I had to take a break 🚽🫣.
Since I am still waiting on hearing back from from the Pinboard.in creator about their API status, I used the time I had to work on a new ap idea of mine. It’s about an app to manage the chores in our house and who’s doing what. We had a system to manage it for about two years now. Our old method used pen and paper and we reached its limit. The new app will hopefully let work better.
The streaming was fun. I didn’t have anybody watching the stream. But I didn’t mind. I did receive my first at spam comment though! 🥳 I regard that as progress: A first step out of irrelevance 😂
Since I am without client projects right now for reasons I will get into later, I simply will use the time to stream and build my app.
If you want to have a look within the next days: