pgadmin-org / pgadmin-org/pgadmin4

Replace the pre-built pkg/mac/dmg.DS_Store with a layout generated at build time

Open
#10,421 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Housekeeping
Dominant language
Python
Stars
3.8k
Forks
891
Avg merge
4d 7h
Merged PRs (30d)
8

Description

pkg/mac/dmg.DS_Store is a pre-built binary whose embedded aliases are bound to a volume name and to a path on a developer's machine from 2020. The styling it provides will vanish silently if either ever changes, with no build failure to tell us.

What it contains

strings pkg/mac/dmg.DS_Store shows the window and icon view settings that give the DMG its appearance:

.bwspblob → WindowBounds {{200, 280}, {800, 400}}
.icvpblob → backgroundImageAlias, backgroundType, iconSize, gridSpacing, arrangeBy
            /.background/dmg-background.png
            /Volumes/pgAdmin 4

and an alias still pointing at where it was generated:

/Users/<redacted>/git/pgadmin4-nwjs/dist/rw.pgadmin4-4.29-nwjs.dmg

So it was produced by hand against a 4.29 NWjs build and has been carried along ever since. pkg/mac/build-functions.sh copies it into the volume via create-dmg's --add-file, and passes --skip-jenkins so create-dmg does not try to generate the same settings itself through AppleScript, which does not work in a headless session.

Why it is worth fixing

The aliases inside are bound to a volume named pgAdmin 4, which comes from APP_NAME in web/branding.py. Anyone rebranding a build, or changing that string, gets a DMG with no background and default icon placement, and nothing anywhere reports a problem: the file is still copied, create-dmg still succeeds, the build still passes. The failure is entirely cosmetic and entirely invisible to CI, which is the worst combination for noticing it.

It is also opaque. Nobody can review a change to it, nobody can regenerate it without repeating whatever manual steps produced it in 2020, and the only documentation of its origins is an alias to a directory that no longer exists.

Possible approaches
  • Generate the .DS_Store during the build from a checked-in description, using something like dmgbuild, which takes a Python settings file and handles the window and icon layout without Finder automation. That would make the layout reviewable and would remove the binding to a fixed volume name.
  • Failing that, at minimum add a check that the volume name still matches what the .DS_Store expects, so a mismatch fails the build instead of quietly shipping an unstyled image, plus a note in pkg/mac/ recording how the file was made and what it is tied to.

Found while investigating the hdiutil unmount timeouts on hosted macOS runners; unrelated to that problem, but worth not losing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with pkg/mac/build-functions.sh and web/branding.py to trace how the DMG volume name and existing pkg/mac/dmg.DS_Store are used. Evaluate the proposed build-time generation or validation approach, then run the macOS packaging build to confirm the layout remains styled when APP_NAME changes and that the build reports mismatches instead of silently succeeding.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, macos, python
Domain
build-system, release
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.