From 8041311089addaec5cd0b8088b855cceb0046959 Mon Sep 17 00:00:00 2001 From: Andrew den Hertog Date: Fri, 13 Feb 2026 10:10:02 -0500 Subject: [PATCH 1/2] feat: add trusted extension publishers and fix stable dataFolderName - Add trustedExtensionPublishers for project-accelerate and frontier-rnd to bypass "Trust Publisher" dialog for sideloaded extensions - Add missing dataFolderName for stable build (was only set for insider) ensuring stable Codex uses ~/.codex for user data Co-Authored-By: Claude Opus 4.5 --- prepare_vscode.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/prepare_vscode.sh b/prepare_vscode.sh index e5aeb732c66..5d1f7890546 100755 --- a/prepare_vscode.sh +++ b/prepare_vscode.sh @@ -44,6 +44,7 @@ setpath "product" "keyboardShortcutsUrlMac" "https://go.microsoft.com/fwlink/?li setpath "product" "keyboardShortcutsUrlWin" "https://go.microsoft.com/fwlink/?linkid=832145" setpath "product" "licenseUrl" "https://github.com/genesis-ai-dev/codex/blob/master/LICENSE" setpath_json "product" "linkProtectionTrustedDomains" '["https://open-vsx.org"]' +setpath_json "product" "trustedExtensionPublishers" '["project-accelerate", "frontier-rnd"]' setpath "product" "releaseNotesUrl" "https://go.microsoft.com/fwlink/?LinkID=533483#vscode" setpath "product" "reportIssueUrl" "https://github.com/genesis-ai-dev/codex/issues/new" setpath "product" "requestFeatureUrl" "https://go.microsoft.com/fwlink/?LinkID=533482" @@ -94,6 +95,7 @@ else setpath "product" "applicationName" "codex" setpath "product" "linuxIconName" "codex" setpath "product" "quality" "stable" + setpath "product" "dataFolderName" ".codex" setpath "product" "urlProtocol" "codex" setpath "product" "serverApplicationName" "codex-server" setpath "product" "serverDataFolderName" ".codex-server" From ef6206db82aeb050648ff7952282f44b4fb5d524 Mon Sep 17 00:00:00 2001 From: Andrew den Hertog Date: Fri, 13 Feb 2026 10:10:59 -0500 Subject: [PATCH 2/2] docs: add CLAUDE.md with development instructions Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 323 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 323 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..609d972a484 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,323 @@ +# Codex Development Guide + +This repository builds Codex, a freely-licensed VS Code distribution. It is a fork of [VSCodium](https://github.com/VSCodium/vscodium) with custom branding and configuration. The build process clones Microsoft's vscode repository and modifies it via git patches. + +## Upstream Relationship + +``` +Microsoft/vscode (source code) + ↓ (cloned at specific commit) +VSCodium/vscodium (origin) ──patches──→ VSCodium binaries + ↓ (forked) +This repo (Codex) ──patches──→ Codex binaries +``` + +**Remotes:** +- `origin` = VSCodium/vscodium (upstream we sync from) +- `nexus` = BiblioNexus-Foundation/codex (our main repo) + +## Repository Structure + +``` +patches/ # All patch files that modify vscode source + *.patch # Core patches applied to all builds + insider/ # Patches specific to insider builds + osx/ # macOS-specific patches + linux/ # Linux-specific patches + windows/ # Windows-specific patches + user/ # Optional user patches + +vscode/ # Cloned vscode repository (gitignored, generated) +dev/ # Development helper scripts +src/ # Brand assets and configuration overlays +``` + +## Working with Patches + +### Understanding the Patch Workflow + +1. **Patches are the source of truth** - Never commit direct changes to the `vscode/` directory. All modifications to VS Code source must be captured as `.patch` files in the `patches/` directory. + +2. **Patches are applied sequentially** - Order matters. Core patches are applied first, then platform-specific patches. + +3. **Patches use placeholder variables** - Patches can use placeholders like `!!APP_NAME!!`, `!!BINARY_NAME!!`, etc. that get replaced during application. + +### Making Changes to VS Code Source + +#### Step 1: Set Up Working Environment + +```bash +# Fresh clone of vscode at the correct commit +./get_repo.sh + +# Or use dev/build.sh which does this automatically +./dev/build.sh +``` + +#### Step 2: Apply Existing Patches + +To work on an existing patch: +```bash +# Apply prerequisite patches + the target patch for editing +./dev/patch.sh prerequisite1 prerequisite2 target-patch + +# Example: To modify the brand.patch +./dev/patch.sh brand +``` + +The `dev/patch.sh` script: +- Resets vscode to clean state +- Applies the helper settings patch +- Applies all listed prerequisite patches +- Applies the target patch (last argument) +- Waits for you to make changes +- Regenerates the patch file when you press a key + +#### Step 3: Making Changes + +After running `dev/patch.sh`: +1. Edit files in `vscode/` as needed +2. Press any key in the terminal when done +3. The script regenerates the patch file automatically + +#### Manual Patch Creation/Update + +If working manually: +```bash +cd vscode + +# Make your changes to the source files +# ... + +# Stage and generate diff +git add . +git diff --staged -U1 > ../patches/your-patch-name.patch +``` + +### Testing Patches + +#### Validate All Patches Apply Cleanly + +```bash +./dev/update_patches.sh +``` + +This script: +- Iterates through all patches +- Attempts to apply each one +- If a patch fails, it applies with `--reject` and pauses for manual resolution +- Regenerates any patches that needed fixing + +#### Full Build Test + +```bash +# Run a complete local build +./dev/build.sh + +# Options: +# -i Build insider version +# -l Use latest vscode version +# -o Skip build (only prepare source) +# -s Skip source preparation (use existing vscode/) +``` + +### Common Development Tasks + +#### Creating a New Patch + +1. Apply all prerequisite patches that your change depends on +2. Make your changes in `vscode/` +3. Generate the patch: + ```bash + cd vscode + git add . + git diff --staged -U1 > ../patches/my-new-feature.patch + ``` +4. Add the patch to the appropriate location in `prepare_vscode.sh` if it should be applied during builds + +#### Updating a Patch After Upstream Changes + +When VS Code updates and a patch no longer applies: +```bash +# Run update script - it will pause on failing patches +./dev/update_patches.sh + +# Fix the conflicts in vscode/, then press any key +# The script regenerates the fixed patch +``` + +#### Debugging Patch Application + +```bash +cd vscode +git apply --check ../patches/problem.patch # Dry run +git apply --reject ../patches/problem.patch # Apply with .rej files for conflicts +``` + +## Key Scripts Reference + +| Script | Purpose | +|--------|---------| +| `get_repo.sh` | Clone vscode at correct version | +| `prepare_vscode.sh` | Apply patches and prepare for build | +| `build.sh` | Main build script | +| `dev/build.sh` | Local development build | +| `dev/patch.sh` | Apply patches for editing a single patch | +| `dev/update_patches.sh` | Validate/update all patches | +| `utils.sh` | Common functions including `apply_patch` | + +## Build Environment + +The build process: +1. `get_repo.sh` - Fetches vscode source at a specific commit +2. `prepare_vscode.sh` - Applies patches, copies branding, runs npm install +3. `build.sh` - Compiles the application + +Environment variables: +- `VSCODE_QUALITY`: "stable" or "insider" +- `OS_NAME`: "osx", "linux", or "windows" +- `VSCODE_ARCH`: CPU architecture + +### Version Tracking + +The VS Code version to build is determined by: + +1. **`upstream/stable.json`** (or `insider.json`) - Contains the target VS Code tag and commit: + ```json + { + "tag": "1.100.0", + "commit": "19e0f9e681ecb8e5c09d8784acaa601316ca4571" + } + ``` + +2. **`VSCODE_LATEST=yes`** - If set, queries Microsoft's update API for the latest version instead + +When syncing upstream, update these JSON files to match VSCodium's versions to ensure patches are compatible. + +## Syncing with Upstream VSCodium + +This is the most challenging maintenance task. VSCodium regularly updates their patches and build scripts to support new VS Code versions. + +### Check Current Status + +```bash +git fetch origin +git log --oneline origin/master -5 # See upstream's recent changes +git rev-list --count $(git merge-base HEAD origin/master)..origin/master # Commits behind +``` + +### Codex-Specific Customizations to Preserve + +When merging upstream, these are our key customizations that must be preserved: + +1. **Branding** (`src/stable/`, `src/insider/`, `icons/`) + - Custom icons and splash screens + - Keep all Codex assets + +2. **GitHub Workflows** (`.github/workflows/`) + - Simplified compared to VSCodium + - Uses different release repos (genesis-ai-dev/codex, BiblioNexus-Foundation/codex) + - Has custom workflows: `docker-build-push.yml`, `patch-rebuild.yml`, `manual-release.yml` + +3. **Windows MSI Files** (`build/windows/msi/`) + - Files renamed from `vscodium.*` to `codex.*` + - References updated for Codex branding + +4. **Product Configuration** (`product.json`, `prepare_vscode.sh`) + - URLs point to genesis-ai-dev/codex repos + - App names, identifiers set to Codex + +5. **Custom Patches** (`patches/`) + - `patches/user/microphone.patch` - Codex-specific + - Minor modifications to other patches for branding + +### Merge Strategy + +#### Option A: Incremental Merge (Recommended for small gaps) + +```bash +# Create a working branch +git checkout -b upstream-sync + +# Merge upstream +git merge origin/master + +# Resolve conflicts - most will be in: +# - .github/workflows/ (keep ours, incorporate new build steps if needed) +# - patches/*.patch (need careful merge - see below) +# - build/windows/msi/ (keep our codex.* files) +# - prepare_vscode.sh (keep our branding, adopt new build logic) +``` + +#### Option B: Cherry-pick Patch Updates (Recommended for large gaps) + +When far behind (like 1.99 → 1.108), it's often easier to: + +1. **Identify patch update commits** in upstream: + ```bash + git log origin/master --oneline --grep="update patches" + ``` + +2. **Cherry-pick or manually apply** the patch changes: + ```bash + # See what patches changed in a specific upstream commit + git show -- patches/ + ``` + +3. **Copy updated patches** from upstream, then re-apply our branding changes + +#### Option C: Reset and Re-apply Customizations + +For very large gaps, it may be cleanest to: + +1. Create a fresh branch from upstream +2. Re-apply Codex customizations on top +3. This ensures we get all upstream fixes cleanly + +### Resolving Patch Conflicts + +When upstream updates patches that we've also modified: + +1. **Compare the patches:** + ```bash + git diff origin/master -- patches/brand.patch + ``` + +2. **Accept upstream's patch structure** (they've adapted to new VS Code) + +3. **Re-apply our branding on top:** + - Our changes are usually just `VSCodium` → `Codex` type substitutions + - The placeholder system (`!!APP_NAME!!`) handles most of this automatically + +### After Merging: Validate Everything + +```bash +# 1. Update upstream/stable.json to new version if needed +# 2. Test patches apply cleanly +./dev/update_patches.sh + +# 3. Run a full local build +./dev/build.sh -l # -l uses latest VS Code version + +# 4. If patches fail, fix them one by one +# The update_patches.sh script will pause on failures +``` + +### Common Conflict Patterns + +| File/Area | Typical Resolution | +|-----------|-------------------| +| `.github/workflows/*.yml` | Keep our simplified versions, cherry-pick important CI fixes | +| `patches/*.patch` | Take upstream's version, verify our branding placeholders work | +| `prepare_vscode.sh` | Keep our branding URLs/names, adopt new build logic | +| `build/windows/msi/` | Keep our `codex.*` files, apply equivalent changes from `vscodium.*` | +| `README.md` | Keep ours | +| `product.json` | Keep ours (merged at build time anyway) | + +## Tips + +- Always work from a clean vscode state when creating patches +- Keep patches focused and minimal - one logical change per patch +- Test patches apply to a fresh clone before committing +- The `vscode/` directory is gitignored - your patch files are the persistent record +- When syncing upstream, focus on patch files first - they're the core of the build