DEV Community: Doug Bridgens

How I use git on multiple devices

Doug Bridgens — Mon, 20 May 2024 14:43:03 +0000

In the last few years I've been using Working Copy on iPhone/iPad to refine README, code comments, and func/var naming, as part of feature development.

Doing this on devices without the ability to change code has been a big quality driver for me. The draw back is a few unconventional commits at the end of a feature branch.

The commit history can easily get messy, with checkpoint or the evil twins typo and update. Passing temporary changes on my feature branch, up into GitHub, so I can view changes on multiple devices gets a little ugly.

I posted a question about how others have solved this, about what process others use. @ridays2001 gave a good solution 👍

TL;DR

Create a throw away WIP branch from the feature branch, and pull the changes back to your feature branch with a merge --squash.

$ git checkout -b kitchen_orders
  # do main code changes

# setup your wip branch and make accessible
$ git checkout -b wip_kitchen_orders
$ git push --set-upstream origin wip_kitchen_orders
  # do minor updates and changes on this branch

# pull wip changes back onto feature branch
$ git checkout kitchen_orders
$ git merge --squash wip_kitchen_orders

# commit the wip changes as one
$ git commit -a -m 'improves godoc comments'

# clean up wip branch
$ git push origin --delete wip_kitchen_orders
$ git branch -D wip_kitchen_orders

These can all be aliased within the shell.

How it works

Here's a summary write-up showing what you need to know, for multi-device changes with a clean git history.

I'm building out my fictional restaurant app, and want to add store and retrieve kitchen orders.

A feature branch for this change:

$ checkout -b kitchen_orders
Switched to a new branch 'kitchen_orders'

I do a bunch of changes as normal, and end up with:

$ git log --oneline
a45fa9e (HEAD -> kitchen_orders, origin/kitchen_orders) adds kitchen order datastore
2f77e62 adds swp to gitignore
4491447 adds fsvault external package
80df0ca adds config pkg to kitchen

Before I create a PR to merge back to develop, I want to read through the changes and make sure I will understand it in three months time. In a team environment this helps make PR reviews easier too.

So I create a WIP branch from my feature branch, and push that to Github.

$ git checkout -b wip_kitchen_orders          
Switched to a new branch 'wip_kitchen_orders'

$ git push --set-upstream origin wip_kitchen_orders
branch 'wip_kitchen_orders' set up to track 'origin/wip_kitchen_orders'.

This WIP branch is for messy commits, and is used to push and pull changes between devices (iPhone, iPad). It lets me do my own code review in a cafe with a pastry, in a civilised way 😁

For me, this code review process is almost more important than the actual code. It's really a review of how understandable I'm leaving things for my future self.

Depending on the feature/change I may make many updates to improve the readability over a few days, with whatever device I have to hand.

Typically this is what I end up with. A bunch of meaningless commit messages, but essential refinements underneath.

$ git log --oneline
a04d7a6 (HEAD -> wip_kitchen_orders) typo
dadc12a stupid typo
8c0dd3c updates function godoc comments
a45fa9e (origin/wip_kitchen_orders, origin/kitchen_orders, kitchen_orders) adds kitchen order datastore
2f77e62 adds swp to gitignore
4491447 adds fsvault external package
80df0ca adds config pkg to kitchen

Now for the magic. I can pull these WIP changes back into my feature branch without a merge commit.

I switch back to my feature branch, and check it's clean.

$ git checkout kitchen_orders
Switched to branch 'kitchen_orders'
Your branch is up to date with 'origin/kitchen_orders'.

$ git status
On branch kitchen_orders
Your branch is up to date with 'origin/kitchen_orders'.

nothing to commit, working tree clean

Then I can merge my WIP branch with squash to pull over the changes without any commit.

$ git merge --squash wip_kitchen_orders
Updating a45fa9e..a04d7a6
Fast-forward
Squash commit -- not updating HEAD
 kitchen/internal/datastore/order.go | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

$ git status
On branch kitchen_orders
Your branch is up to date with 'origin/kitchen_orders'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   kitchen/internal/datastore/order.go

This leaves me able to apply these WIP changes as a single commit on my feature branch, as if the WIP branch never existed.

So I end up with a long term git log graph like this:


$ alias gl='git log --graph --pretty="%C(green) %d %C(red)Date: %ad %C(yellow) %s" --date=human'

$ gl
*     (HEAD -> develop, origin/develop, origin/HEAD) Date: 27 seconds ago  Merge pull request #5 from thisdougb/kitchen_orders
|\  
| *   (origin/kitchen_orders, kitchen_orders) Date: 82 seconds ago  improves datastore godoc comments
| *   Date: 33 minutes ago  adds kitchen order datastore
| *   Date: 52 minutes ago  adds swp to gitignore
| *   Date: 54 minutes ago  adds fsvault external package
| *   Date: 80 minutes ago  adds config pkg to kitchen
|/  
*     Date: Wed May 1 13:57  Merge pull request #4 from thisdougb/thisdougb-patch-1
|\  
| *   Date: Wed May 1 13:57  Update README.md
|/  
*     Date: Wed May 1 13:55  Merge pull request #3 from thisdougb/part1b

And remember to clean up:

$ git push origin --delete wip_kitchen_orders
To github.com:thisdougb/go-eat.git
 - [deleted]         wip_kitchen_orders
$ git branch -D wip_kitchen_orders
Deleted branch wip_kitchen_orders (was a04d7a6).
$

The nice thing about this method is that it's really simple. I can create a WIP branch when I need to, within Working Copy or from another device.

How do you use git between devices?

Doug Bridgens — Tue, 07 May 2024 09:55:31 +0000

If I'm working on a feature, on a branch, I struggle to do that while working 'remotely'.

When I work remotely I don't mean from the kitchen table, in a wfh style. My use-case is doing a couple of hours on a desktop at home, then maybe continuing on the train with a laptop as I travel to see some friends. Or going away for a few days and doing a couple of hours coding every morning.

I also use git history to keep track of progress, or track down rogue commits. So trying to maintain meaningful (one line) commit messages is important.

Through the years I've never found a good way to maintain a meaningful git history, while updating code on different devices. It's often too impractical to commit fully worked features, because I'm not actually finished yet but have to go off somewhere.

I've effectively created a desire line, by committing and pushing whatever I have as a checkpoint so I can continue the work on another device.

For example. I'm adding a new function as part of a feature, at home on a desktop. I don't quite have time to get it finished before I have to leave for a meeting. But I can use the sixty minute train ride to finish the work, using my laptop.

I'd just commit what's done with a message of checkpoint. Then twenty minutes later pull changes on the branch from my laptop, and finish it off.

The ideal would be a git log of commits with the checkpoint (or transfer) commits removed, while meaningful commits remain.

But I'm interested to know if anyone else has a better method?

What I'm thinking is somehow automating the following, maybe via an alias function or git hook.

Current state:

$ git log --oneline      
9ac99be (HEAD -> feature) meaningful 2
1736b60 checkpoint
5de2fe5 meaningful 1

Move HEAD back to the last meaningful commit, but leaving the code intact:

$ git reset --soft HEAD~2

$ git log --oneline      
5de2fe5 (HEAD -> feature) meaningful 1
9679310 (develop) initial commit

$ git status             
On branch feature
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   main.go

Now commit the next change:

$ git commit -m 'meaningful 2'
[feature 6fd925e] meaningful 2

$ git log --oneline           
6fd925e (HEAD -> feature) meaningful 2
5de2fe5 meaningful 1
9679310 (develop) initial commit

$ git diff 6fd925e~       
diff --git a/main.go b/main.go
index f33752a..8e3863f 100644
--- a/main.go
+++ b/main.go
@@ -4,4 +4,6 @@ import "fmt"

 func main() {
        fmt.Println("meaningful 1")
+       fmt.Println("checkpoint")
+       fmt.Println("meaningful 2")
 }

Building a monolith in Go - Layout

Doug Bridgens — Wed, 01 May 2024 12:45:43 +0000

I'm building a reasonably sized commercial app in Go. By sharing decisions and choices (using a fictional restaurant app) I am hoping it may solicit advice from better developers, possibly help others, and generally force me to reflect when writing it out.

The crucial point in scaling a business is when you hire enough developers to be able to specialise effort. That jump from one, two, or five developers working on a shared code-base to multiple teams with their own responsibilities.

This is the moment you have to completely refactor the spaghetti, or have an easy ride to a service architecture. Or probably somewhere in between. Having done this many times I think it's possible to have an easy ride, if and when the time comes to scaling.

Go's package system is very simple, and really suits separated concerns in distinct repo's. However, the practicality of continuously updating local copies becomes a real drag for a small startup. Deploying and versioning multiple services adds to the friction and cost.

By contrast, a monolith is simple. Particularly with Go packages, a monolith layout can emulate a service architecture. If this is possible then we gain simple deployments and a simple dev process.

The key is to build and layout the monolith in a way that makes it easy to extract components later on. While avoiding the (process, infrastructure) overhead of a micro-service architecture from day one.

Package Layout

My fictional restaurant Go Eat has five principle areas of concern. So I create a top-level package for each:

./goeat/booking
./goeat/menu
./goeat/staff
./goeat/service
./goeat/kitchen

I have tried so many layouts that I now realise layout is not strong enough on its own to force good habits. It would be very easy to create a mess from this layout, with deep calls between packages that are hard to unpick.

Domain Boundaries

One of the nasties that hits companies when the try and scale is monolith mess. Code execution paths that are so intertwined that the pragmatic path to scale is rewriting the app. That's a costly way of scaling, but at least you know what it should do.

I want to avoid creating this mess by using Go's internal package qualifier. For example, when writing functions in kitchen I want to prevent dipping into staff because it's convenient.

Go's package export method (capitalised type names) is too lax for my case, at the service/domain/parent-package level. I want to protect package exports inter-service, but still use them intra-service.

To solve this I am using a clearly named publicapi.go file at the top of each (service) package tree. And by protecting all other functions under internal I have enforcement.

./goeat/kitchen/
./goeat/kitchen/internal/rota.go

./goeat/staff/
./goeat/staff/publicapi.go
./goeat/staff/internal/calendar/main.go

My kitchen service needs to update its rota from the calendar package in the staff service. So I create a public API route into staff like this:

// ./goeat/staff/publicapi.go

package staff

import "goeat/staff/internal/calendar"

var (
        GetKitchenRota = func() []string {
                return calendar.GetRota("kitchen")
        }
)

It's really just a local version of an http API. Which will make a future transition easier to do.

And calling this from the kitchen service looks like this:

// ./goeat/kitchen/internal/rota.go

package rota

import (
    "goeat/staff"
)

func fetchRota() []string {

    rota := staff.GetKitchenRota()

    // do something with the rota

    return rota
}

A readability bonus is the name of the import being staff. The domain is much clearer than using a sub-package export, which would result in calendar.GetRota.

Testing

Implementing the public 'api' methods as vars enables me to isolate testing between services.

It is trivial to mock the responses from the staff service, independently of that package. I haven't found a simpler way of doing this, every other way seems to involve code gymnastics with interfaces or channels. This particular use-case is emulating services within a monolith.

A simple test example in the kitchen service:

//go:build test

// ./goeat/kitchen/internal/rota/main_test.go

package rota

import (
    "goeat/staff"
    "testing"

    "github.com/stretchr/testify/assert"
)

func TestFetchRota(t *testing.T) {

    mockRota := []string{"A", "B"}
    mockStaffGetKitchenRota := func() []string {
        return mockRota
    }

    // override the 'api' response with our mock function
    staff.GetKitchenRota = mockStaffGetKitchenRota

    assert.Equal(t, fetchRota(), mockRota, "expect A, B")
}

In this way I can develop features in one service (kitchen) without touching the code in other services. Fewer typos, fewer bugs.

Summary

My choice to develop an app as a monolith depends on a bunch of particular use-case factors.

I think Go's inherent simplicity around packages make it easy to create domain boundaries. This makes the whole code-base simpler to think about.

Simplicity is key, because with few (or solo) developers complexity kills motivation. Speed of development is often less about CPU cycles, and more about efficient process.

A single deployable binary is easier to manage and test, at small scale. Although Go suits a discrete service-architecture, the overhead (repo's, ci, infra) is too much right now.

The sample code is on GitHub, which I'll update as I go: Go Eat

Apple Mouse Design Fail Solved With Bash

Doug Bridgens — Fri, 26 Apr 2024 09:28:59 +0000

The Apple Mouse charging port is a weird design, because while charging the mouse it cannot be used. Aesthetics won out over user productivity.

On the one hand I appreciate that one hour of charging time every few weeks is a marginal outage. Infrequent enough that the disruption is almost forgotten each time.

Though on the other hand Mac OS is pretty unusable without a mouse. So my expensive iMac is bricked because the mouse has lies upside down with cable plugged into its belly.

But hey, I can appreciate the nice aesthetic while I sit and watch it charging. Oh wait..there's no pop-up charging indicator either, so I just guess when it's 100% 😡

And my mouse alway seems to run out of power when I'm fully into whatever I'm doing. Does this just happen to me?

I just couldn't stand it anymore, so I built a battery level warning script that I run in the background. If the mouse or keyboard fall below 20% charge then I get a simple pop-up window.

It's a gentle reminder to charge when I next leave my desk. No rush, no outage, because with 20% I still have a few days of battery left. I typically just plug it in when I finish that day.

tomtastic made some good improvements to the inner workings. And we made sure only two pop-up reminders per day, which feels about right.

It's a pretty simple bash script run from cron. Aesthetics may have won the design process at Apple, but we can solve the productivity problem it caused.

It's on GitHub: MagicPowerAlert

I got a pop-up this morning, which reminded me of the script running quietly in the background. And I am out for a meeting this afternoon, so I'll plug it in before I go. Whenever the pop-up appears it feels like a little win over poor design.

Create GPS Test Data In Go

Doug Bridgens — Wed, 24 Apr 2024 15:43:50 +0000

Many of the functions I'm working on consume arrays of points (GPS tracks) []float64{lng,lat} on which to run statistical analysis. Individual tracks can have 50,000+ points, describing a real journey from A to B.

Testing functions that process GPS tracks has been unexpectedly difficult. Test data of the form [1.0,2.0], to test logically is fine. But beyond that, I want to be able to test consistency in things like finding clusters, or coefficient breakpoints.

For testing I'm not concerned with where the locations are on earth, but it's handy to be able to view tracks on a map for visual confirmation. So the coordinates need to, sort of, coordinate.

I've created a function that generates semi-coherent GPS location data tracks. It's trivial to create a 5,000 data input track, designed to test something in particular. Being able to export it as geoJSON and view the shape on map is good for speedy intuition checks.

I can setup the data to be skewed one way or another, or insert a cluster of weirdness. Particularly useful at larger data sizes, where one analysis method may be better than another.

func CreateGPSData() {

        line := orb.LineString{orb.Point{-3.188267, 55.953251}}

        // general direction and distance per point
        bearingRange := [2]int{Direction_SSE, Direction_SSW}
        distanceRange := [2]int{10 * 1000, 15 * 1000}

        // generate a test GPS track
        for range 5000 {
                newPoint := generateNewLocation(line[len(line)-1],
                        bearingRange,
                        distanceRange)
                line = append(line, newPoint)
        }

        // add skewness in the data
        bearingRange = [2]int{Direction_W, Direction_WNW}
        distanceRange = [2]int{1000, 1500}
        for range 100 {
                newPoint := generateNewLocation(line[len(line)-1],
                        bearingRange,
                        distanceRange)
                line = append(line, newPoint)
        }

        // do testing
}

What doesn't seem to be too common is generating a new point, some distance away in a particular direction. The opposite of point.DistanceTo(point2). That's really all that the following function does.

The breakdown starts with some readability. Using compass rose names really helps with reading the calling function.

// the compass rose, naming format for readability
const (
        Direction_N = iota
        Direction_NNE
        Direction_NE
        Direction_ENE
        Direction_E
        Direction_ESE
        Direction_SE
        Direction_SSE
        Direction_S
        Direction_SSW
        Direction_SW
        Direction_WSW
        Direction_W
        Direction_WNW
        Direction_NW
        Direction_NNW
)

const (
        compassRoseDegrees = 22.5
)

Rather than simply a series of linear points, I want a GPS track that wiggles a little. So the parameters are a range of direction and distance, giving a small amount of randomness when calculating the next point.

// generateNewLocation returns a new point in the range of direction and
// distance. It is meant to build non-repetitive but predictable GPS tracks, to
// help generate test input cases.
//
// It's also meant to be readable code.
func generateNewLocation(start orb.Point, direction [2]int, distance [2]int) orb.Point {

Possibly the most common stupid mistakes I make are mixing up longitude and latitude indexes through typos. Named index values solve this.

// Mistakes with lon/lat indexing area easy to make, explicit index names
// helps
const (
    Longitude = 0
    Latitude  = 1
)

I use the excellent orb package to hide much of the GPS specific calculations.

A point to note is that the Go maths package works in radians, so here's a helper function.

var (
    latitudeOneDegreeOfDistance = 111000  // metres
    newPoint                    orb.Point // []float64{Long, Lat}

    // convert from degrees to radians
    deg2rad = func(d float64) float64 { return d * math.Pi / 180 }
)

A while ago I went back to study maths, and have found lots of use for it. Here using trig to workout the distances on the ground.

 // Use trigonometry of a right angled triangle to solve the distances on the ground.
// The hypotenuse is our desired distance to travel,  and one angle
// is our desired bearing.
//
// now work out the vertical (longitude) and horizontal (latitude) sides in
// distance units.
hyp := (rand.Float64() * float64(distance[1]-distance[0])) + float64(distance[0])

// Get the compass bearing in degrees, with a little randomness between the
// general direction. Non-linear tracks are easier to troubleshoot visually.
bearingMin := float64(direction[0]) * 22.5
bearingMax := float64(direction[1]) * 22.5
angle := (rand.Float64() * (bearingMax - bearingMin)) + bearingMin

// Calulate the other side lengths using SOH CAH TOA. The Go math package
// works in radians
adj := math.Cos(deg2rad(angle)) * hyp // adjacent side of angle
opp := math.Sin(deg2rad(angle)) * hyp // opposite side of angle

Each degree change in latitude moves a fixed distance on the earth surface. So it is fairly simple to find the degree change we need to move our required distance on the ground.

// Each degree change in every latitude equates to ~111 km on the ground. So
// now find the degree change required for the length of adj
latitudeDelta := (1.0 / float64(latitudeOneDegreeOfDistance)) * adj
newPoint[Latitude] = start[Latitude] + latitudeDelta

Longitude 'distance moved on the earth surface' on the other hand changes depending on the corresponding latitude.

First need to find what one longitude degree of travel is, at the current latitude. This is the longitude equivalent to latitudeOneDegreeOfDistance = 111000.

// Distance on the ground for each degree of longitude changes depending on
// latitude because the earth is not perfectly spherical. So we need to
// calculate the distance of one degree longitude for our current latitude.
p1 := orb.Point{1.0, start[Latitude]}
p2 := orb.Point{2.0, start[Latitude]}
longitudeOneDegreeOfDistance := geo.Distance(p1, p2) // returns metres

After which it's the same calculation to find the longitude degree required to move our required distance on the ground.

// Now we can use this value to calculate the longitude degree change
// required to move opp distance (in a horizontal straight line) at this
// latitude.
longitudeDelta := (1.0 / longitudeOneDegreeOfDistance) * opp

Now we have the new point, located roughly at the direction and distance required.

// The new point is a vertical and horizontal shift to arrive at hyp
// distance from the start point on the required bearing.
newPoint[Longitude] = start[Longitude] + longitudeDelta

return newPoint

To print the geoJSON object, which can be viewed using the Mapbox viewer. The geojson package is part of orb.

fc := geojson.NewFeatureCollection()
f := geojson.NewFeature(line)
fc.Append(f)

rawJSON, _ := fc.MarshalJSON()
fmt.Println(string(rawJSON))

The geoJSON output, which can be dropped right into the Mapbox viewer.

{"features":[{"type":"Feature","geometry":{"type":"LineString","coordinates":[[-3.188267,55.953251],[-3.135746915373942,55.86790144687853],[-3.1203515713600174,55.77480489552086],[-3.1047549460145367,55.67255911652837],[-3.157869557083529,55.55060126862168],[-3.228498091310353,55.43475670091365],[-3.2496225715462885,55.436812333443044],[-3.2661004391340707,55.439707415244094],[-3.2813563020992547,55.44313063594729],[-3.3021255075874594,55.44562577470332],[-3.319279338837285,55.446998922512265]]},"properties":{"stroke":"#b464d6","stroke-width":3}}],"type":"FeatureCollection"}

The full code is in a Gist here.

What Happens After Agile Dies?

Doug Bridgens — Thu, 11 Apr 2024 17:20:36 +0000

I started development in 1990, working on a Unix OS written in C. Our 'office' back then was called a lab, we revered old-timers who often only worked at night, and software patches were emailed as file diffs.

Google, Linux, Amazon, cookies, wifi, laptops, etc, all yet to come. Peak excitement was DNS becoming popular and usable, enabling something called the World Wide Web.

In the early days I worked on a product called SCAFS, which was a hardware cache between the OS and hard drives. It cached SQL queries, delivering above 20x performance. Very smart back in the days of SCSI ribbons.

We were a diverse small team of hardware, systems, marketing, sales. There were bugs and features, and a general roadmap. We talked a lot with customers, consulting or at trade shows.

Our product was autonomous, yet integrated with the OS dev team, high-performance server team, and external database companies. I think we shipped hardware/software rev's every three months, with bug fixes going out quicker (on magnetic tapes!).

Looking back, it feels like I had an informal apprenticeship. I met so many different types of people and different ways of working on things. The people and culture taught me to be responsible, do what I commit to, and the importance of effective communication.

Today I can easily recognise that we were a fast moving team that was able to work asynchronously.

The very definition of agile.

But we had no formal culture-framework imposed upon us. Rather than be infantilised and micro-managed, we were expected to be adults. Ideas and opinions travelled freely, whereas now they are siloed off (irony!) by dogmatic Kafka-esque processes.

I despair at what business has done to the process of technology development. Agile is the business version of engineering process, sold to developers as self-empowerment. It is a cult that feeds on narcissism.

More agile, less Agile.

These days, while I work solo on a web app, I think a lot about coding less. 11,000 lines-of-code probably has fewer bugs than 22,000? One risk of solo development is that your project is suffocated by time spent fixing bugs. There's a business motive here.

Writing less code is of course quicker to do, but it requires spending more time on the engineering process. Better engineering means less code, means more engineering time, etc.

I try to deploy weekly. My commitment to my future self is that I must include 'how to troubleshoot this feature' in the docs. My template is below.

Monday to Thursday I work up my plan while walking or doing other things. Great ideas seem to surface when you least think about them. Long walks in interesting places seem to be the best place to rationalise thoughts.

Friday to Sunday is when I code. When there are no design decisions left to make, coding is really easy and quick.

This goes against Agile, against what many have only known. You can try it, and see what happens. Try a challenge from AdventOfCode, spend a couple of days working up a plan first. Did you write a cleaner solution? Now extrapolate.

This 80% thinking and 20% coding may seem counter-intuitive at first. But it results in faster development, lower operational costs, and higher motivation. It just changes things, when you realise good software development is not really about writing code.

Maybe not today. Maybe not tomorrow, but soon and for the rest of your life.

This way of planning is not really anything new. It's centred on trying to communicate change more effectively. In my case, currently, I'm communicating with my future self via a walkthrough.

My assumption is always that no-one spends time doing a literal code review any more. So if someone reviews my walkthrough, and I commit to writing code that reflects it, that's a proxy for a meaningful code review.

However we do software post-Agile, businesses that ditch micro-management and embrace autonomous asynchronous work will make better software.

Template

I created this template in the Things3 app on Mac and iOS. I wanted simple task management, that I could read and edit on the move. The ability to show tasks in a Home Screen widget is great for keeping scope limited.

#### Trigger

What happened to make this worth doing.

#### Purpose

What functionality MUST be delivered.

#### Strategy

- High level decisions I will take to do this.

#### Thoughts

- Any context to decision making, peripheral things, knock-on's, etc.

#### Walkthrough

- [ ] First thing to do

A task description. Adding pseudo code lets me evolve function/var names and types as I build up the walkthrough tasks.

func loadData(id int64) account.Data {
    if !dataExists(id) {
        fetchData(id)
    }
    return getData(id)
}

- [ ] Second thing to do

Of course I'm generalising about Agile. It's not all bad (hey future employers!). But we do lose something when business runs software development.