From fabc03289068a3d9d66515c001834c1230b4e126 Mon Sep 17 00:00:00 2001
From: Kyle Harding <kyle@balena.io>
Date: Wed, 18 Dec 2024 16:21:27 -0500
Subject: [PATCH] Create a balena/main branch for customizations

Signed-off-by: Kyle Harding <kyle@balena.io>
---
 .github/workflows/sync-fork.yml | 31 +++++++++++++++++++++++
 BALENA.md                       | 45 +++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 .github/workflows/sync-fork.yml
 create mode 100644 BALENA.md

diff --git a/.github/workflows/sync-fork.yml b/.github/workflows/sync-fork.yml
new file mode 100644
index 00000000..2040bb3a
--- /dev/null
+++ b/.github/workflows/sync-fork.yml
@@ -0,0 +1,31 @@
+name: Sync fork with upstream
+
+on:
+  schedule:
+    # Run every 8 hours at 42 minutes
+    - cron: '42 */8 * * *'
+  # Allow manual triggers
+  workflow_dispatch:
+
+jobs:
+  sync-fork:
+    runs-on: ubuntu-latest
+    name: Sync fork
+
+    steps:
+      # https://github.com/actions/checkout
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        with:
+          persist-credentials: false
+          token: ${{ secrets.SYNC_FORK_TOKEN }}
+
+      # https://github.com/repo-sync/github-sync
+      - name: GitHub Sync
+        uses: repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88 # v2.3.0
+        with:
+          source_repo: https://github.com/github/safe-settings.git
+          source_branch: "*" # Sync all branches
+          destination_branch: "*" # Sync all branches
+          github_token: ${{ secrets.SYNC_FORK_TOKEN }}
+          sync_tags: "true"
diff --git a/BALENA.md b/BALENA.md
new file mode 100644
index 00000000..7aed7438
--- /dev/null
+++ b/BALENA.md
@@ -0,0 +1,45 @@
+# Maintaining a fork of safe-settings for balena
+
+## Goals
+
+Maintain a fork of safe-settings that allows both ease of testing, and streamlined contributions upstream.
+
+The fork branches and tags should always mirror upstream for ease of development.
+
+The fork should hide its customizations in a side branch so we do not need to constantly rebase our feature branches, or accidentally contribute these customizations upstream.
+
+## Sync upstream branches and tags
+
+We retain a `balena/main` branch with customizations as the default branch of the fork.
+
+A scheduled workflow in this branch includes a sync fork job to force sync all upstream branches and tags with origin.
+Branches that exist in the fork but do not exist upstream are ignored. Local changes to branches that exist upstream are removed!
+
+See: <https://github.com/repo-sync/github-sync>
+
+## Sync balena/main with upstream
+
+Occasionally we should manually rebase `balena/main` with upstream `main-enterprise` to ensure we have the latest changes.
+
+```bash
+git fetch
+git checkout balena/main
+git rebase origin/main-enterprise
+```
+
+This is not critical as development branches should be based on `main-enterprise` and not `balena/main`.
+
+## Contributing
+
+1. Create a `balena/feature-x` or `balena/fix-x` branch or similar based on `main-enterprise` for testing changes. Do not open a pull request at this time, just work on the branch.
+2. When ready, use the `Create pre-release` workflow dispatch job to generate a tagged release and image.
+
+    > Use workflow from: `balena/feature-x`
+    >
+    > Bump: `patch`
+    >
+    > Prerelease: `withBuildNumber`
+    >
+    > Prelabel: `snapshot`
+
+3. Once changes are tested, a PR can be opened against the upstream `main-enterprise` branch. Do not open a PR with the base `balena/main` as it will not be merged.