tramlinehq · nid90 · Jan 30, 2025 · Jan 30, 2025 · Jan 30, 2025 · Jan 31, 2025
diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,7 @@
 .env.test.local
 .env.production.local
 .idea
+cspell.json
 
 npm-debug.log*
 yarn-debug.log*

diff --git a/docs/api.md b/docs/api.md
@@ -1,32 +1,35 @@
 ---
-sidebar_position: 8
+id: api
+title: 🧪 Tramline API
+sidebar_label: 🧪 Tramline API
+sidebar_position: 7
 ---
 
-# 🧪 Tramline API
+Tramline currently exposes 3 API endpoints to fetch release information and to send custom build metadata. Before you start, you need your API credentials to make requests. To get these click on **Organization Settings** in the top navbar:
 
-Tramline currently exposes three API endpoints to fetch release information and to send custom build metadata to Tramline.
+![](/img/organization-settings-dropdown.png)
 
-You need your `Account ID` and `API Key` before you can make any requests. To get these click on **Settings** in the dropdown on the top-right:
+Under the **Settings** tab, inside the **API** section, you will find the `Account ID` and the `API key` that will be used later for all API calls.
 
-![](/img/org-settings.png)
-
-Here you will find the relevant API settings:
-
-![](/img/api-settings.png)
+<p><img src="/img/api-settings.png" width="400" height="400"/></p>
 
 :::info
-Only a user with owner or developer privileges can access these API settings.
+Only a user with owner or developer privileges can view these API settings.
 :::
 
 ### Get the latest release made to the store for an app
 
+#### Request
+
 ```bash
 curl -H "Authorization: Bearer your-api-key" \
      -H "X-TRAMLINE-ACCOUNT-ID: your-account-id" \
      -H "Accept: application/json" \
      https://tramline.dev/api/v1/apps/<app-id>
 ```
 
+#### Response
+
 This API would respond with a format like this:
 
 ```json
@@ -60,6 +63,8 @@ jq '.latest.android.build_version'
 
 ### Get all release versions sent to the store for a given release
 
+#### Request
+
 You can either specify a particular branch
 
 ```bash
@@ -78,6 +83,8 @@ curl -H "Authorization: Bearer your-api-key" \
      https://tramline.dev/api/v1/releases/<release-id>
 ```
 
+#### Response
+
 This API would respond with a format like this:
 
 ```json
@@ -123,6 +130,8 @@ jq '.releases.android | map(.build_version)'
 
 ### Send custom metadata for a build
 
+#### Request
+
 You can send custom metadata to be displayed on Tramline dashboard about your build. Each metadata should have a unique identifier, and its value can be numerical or textual. The trend of all numeric metadata will be shown on Tramline dashboard.
 
 Examples of metadata: app launch time, unit test coverage etc.
@@ -197,6 +206,7 @@ The `external_metadata` in the request body should adhere to the following schem
 ```
 
 Sample request body:
+
 ```json
 {
     "external_metadata": [
@@ -227,3 +237,7 @@ Sample request body:
     ]
 }
 ```
+
+#### Response
+
+If the schema is valid and the request is successful, the response will be a `200 OK`.
diff --git a/docs/automations.mdx b/docs/automations.mdx
@@ -1,9 +1,10 @@
 ---
-sidebar_position: 7
+id: automations
+title: 🤖 Automations
+sidebar_label: 🤖 Automations
+sidebar_position: 4
 ---
 
-# 🤖 Automations
-
 export const ReleaseBranch = ({name, n}) => {
     function date() {
         const today = new Date()
@@ -21,82 +22,216 @@ export const ReleaseBranch = ({name, n}) => {
     return (<code>r/{name}/{date()}{n ? '-1' : ''}</code>)
 };
 
-Tramline automates away a lot of boilerplate work and opines on some sensible defaults. We will continue to add more automations and hopefully also add controls to chose which ones to run.
+Tramline automates away a lot of boilerplate work and opines on some sensible defaults. We will continue to add more automations and hopefully also add controls to chose which ones to run. Currently, some sensible automations (that everyone should do) are just magically done for you, and some require enabling manually.
+
+If you have suggestions for common processes that Tramline can automate for you, which don't exist in this list down below, [please let us know](mailto:[email protected])!
+
+## Cut a release branch
+
+:::tip
+This automation is run when a [new release is prepared](/using-tramline/release-management/new-release).
+:::
+:::info
+Release branches are only cut for specific branching strategies. See [Branching Strategies](using-tramline/release-management/branching-strategies).
+:::
+
+On starting a new release, we automatically cut a release branch from the configured working branch for the repo. The release branch takes the pattern of `r/name-of-release-train/date-of-release`. For example, if your release train is called **Nightly**, the release branch will be <ReleaseBranch name="nightly" n=''/>. Additional releases during the day will be <ReleaseBranch name="nightly" n='1'/>.
+
+## Pre-release pull requests
+
+:::tip
+This automation is run when a [new release is prepared](/using-tramline/release-management/new-release).
+:::
+:::info
+Only works for [Parallel Working and Release Branch](/using-tramline/release-management/branching-strategies#parallel-working-and-release-branch) strategy.
+:::
+
+```mermaid
+gitGraph
+  branch release
+  commit id: "previously"
+  checkout main
+  commit id: "commit 1"
+  commit id: "commit 2"
+  checkout release
+  merge main tag: "Start of release 1.0.0"
+  checkout main
+  commit id: "commit 3"
+  commit id: "commit 4"
+  commit id: "commit 5"
+  checkout release
+  merge main tag: "Start of Release 1.1.0"
+  checkout main
+  commit id: "commit 6"
+```
 
-This is a list of important things Tramline currently automatically does with little to no user intervention.
+The working branch (eg. `main`) is merged into the static release branch (eg. `release`) automatically at the the start of every release.
 
-## Cutting a release branch
+## Start release flow for new commits
 
-On starting a new release, we automatically cut a release branch from the specified working branch for the repo.
+:::tip
+This automation is run when [new commits land on the release branch](/using-tramline/working-pane/stability).
+:::
 
-This is always in the form of `r/name-of-release-train/date-of-release`.
+When you land fixes to your release branch for an active release, the Tramline release flow automatically kicks off again. If you have Internal Releases enabled, on the arrival of every new commit, a new internal release process will start. If you only have Release Candidates enabled, only the release candidate process will automatically start. When any of this happens, the previous internal or RC builds are marked as stale, so that you can start working on the fresh builds.
 
-For example, if your release train is called **Nightly**, the release branch will be <ReleaseBranch name="nightly" n=''/>. Additional releases during the day will be <ReleaseBranch name="nightly" n='1'/>.
+## Trigger workflows
 
-The release will listen to commits on this branch after it has been created.
+:::tip
+This automation is run when [new commits land on the release branch](/using-tramline/working-pane/stability).
+:::
 
-## Cutting a release tag at the end of a release
+When an internal or release candidate process starts, the associated workflow is automatically triggered. The subsequent updates to that workflow are also tracked and updated in the dashboard.
 
-Once the release is finalized, we automatically tag the last commit that was released with the version generated by the release train. If the released version is `1.0.0`. The tag will be `v1.0.0`.
+## Trigger distributions
 
-If you're using the GitHub integration for source control, we will also create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with an auto-generated changelog.
+:::info
+Enable this in your [submission settings](/using-tramline/release-management/release-settings#submission-settings).
+:::
 
-## Creating and merging pull requests
+When a workflow finishes and a build is found, Tramline can optionally auto-submit the build to the configured distribution channel.
 
-We wholly manage pull requests around release branches while starting and ending a release (depending on the branching strategy selected).
+## Cancel previous workflow run
 
-See [Branching Strategies](/branching-strategies) for more information.
+When a new commit lands, and if there's already a workflow running for a previous commit, Tramline will attempt to cancel the previous workflow run. We do this to avoid wasting compute minutes.
 
-## Managing version names and build numbers
+## Apply change queue
 
-### Build number
+:::info
+Enable build queues in your [release train settings](/using-tramline/release-management/release-settings#advanced-settings).
+:::
 
-Every app that is added to Tramline maintains an atomic counter for the build number. Regardless of what trains are running for the app, every workflow run will internally and externally update the build number for the generated build.
+Changes that land on the release branch can optionally be staged in a [Change Queue](/using-tramline/build-processing/build-queue). The change queue gets automatically drained if either the number of changes in the queue exceed the configured limit or if the configured batch-time has passed.
 
-This ensures that every build generated by Tramline across configured workflows always have a unique value.
+## Track ongoing work
 
-### Version Name
+:::tip
+This automation is always available as long as the release is active. See [changeset tracking](/using-tramline/working-pane/changeset-tracking).
+:::
 
-Version names are processed in a `major.minor.patch` format, where the `patch` term is optional.
+All the pull requests that directly target the release branch (eg. `r/production/2022-12-31-1`) are automatically tracked and updated in the [changeset tracking](/using-tramline/working-pane/changeset-tracking) dashboard.
 
-✅ Allowed versions:
-```
-1.2.0
-4.2.1
-16.9
-```
+![](/img/ongoing-work.png)
 
-❌ Invalid versions:
-```
-1
-1.2.3.4
-```
+## Bumping versions and build numbers
 
-Every new release increments the `minor` version.
+### Versions
 
-Once your release has reached a store (App Store or Play Store) production channel and has been distributed to at least some percentage of users (via staged rollout), any new commit on the release branch increments the `patch` version. When that happens, your release enters a `hotfix` mode.
+Versions are automatically managed by Tramline. New releases start with a minor or major version bump (in SemVer terminology). When fixes land in the middle of a production rollout, the patch version always gets auto-bumped for the new changes.
 
-### Hotfix
+Similarly, when starting new hotfix releases, the patch version always get auto-bumped.
 
-A release in `hotfix` mode simply means that you are pushing changes on the build that has reached some of your user-base and has a bug that warrants immediate fix rather than a new release altogether.
+### Build numbers
 
-### New release
+Every build created generated through Tramline always has a unique build number. This is true across workflows, and across trains. Tramline maintains an atomic counter internally and automatically updates the build number through the [workflow triggering](/using-tramline/working-pane/stability) mechanism.
 
-```
-1.0.0 --> 1.1.0
-```
+## Merging fixes back
 
-### New commits after production distribution has begun
+:::tip
+This is applicable for all [branching strategies](/using-tramline/release-management/branching-strategies).
+:::
+:::tip
+Tramline will always automatically try to merge (not just create) all PRs that are created by Tramline, whenever possible (depending on required checks etc.).
+:::
 
-```
-1.1.0 --> 1.1.1
-```
 
-## Triggering step workflows on commits
 
-When you start a release or when you land commits on a release branch; we automatically run the steps and their workflows and send the builds generated from the workflows to the correct build channels.
+Tramline can automatically backmerge changes from the release branch to your working branch and any upcoming release branches. There are two backmerge strategy options available.
+
+### Continuously as changes land
+
+Any PRs or commits merged into the release branch will be "backmerged" into the working branch. As new changes land, this process repeats so that the working branch is always up to date with the release branch. This is helpful for teams that do a number of fixes directly on the release branch so that the code is merged back to the "trunk" as _quickly_ as possible.
+
+:::info
+Depending on the [VCS integration](/integrations/version-control), the way cherry-picks happen have will slight variations.
+:::
+
+These running PRs created by Tramline are sometimes referred to as _Patch PRs_. These PRs get also get assigned to the original authors of the relevant change/commit.
+
+### End of release
+
+:::info
+A backmerge branch will only be created if commits are found on the release branch that are not on the working branch.
+:::
+
+At the end of the release cycle, Tramline will create a backmerge branch and open a pull request to merge the release branch back into the working branch and also to any upcoming release branch.
+
+## Notifications
+
+:::info
+Enable [Notifications](/using-tramline/quality-and-monitoring/notifications) in your [release train settings](/using-tramline/release-management/release-settings).
+:::
+
+### Attach builds
+
+Along with all the available notifications, the "build available" notification specifically attaches the Internal or Release Candidate build as a part of the Slack notification. This is helpful for QAs or other folks in the configured Slack channel to quickly download the build for testing.
+
+### Tester notes
+
+When a new build is available to download from Tramline, in addition to the build itself, Tramline also sends the list of changes that were made for the build (since the last build) in the Slack notification. This tells anyone who is downloading the build what changes were made in it. The same information is also available in the Tramline dashboard.
+
+## Create VCS tags
+
+:::info
+Enable tagging in your [release train settings](/using-tramline/release-management/release-settings).
+:::
+
+Tramline cuts git tags on your version control in a couple of different scenarios:
+
+### End of a release
+
+When the release ends, we automatically tag the last commit that was released at the end. If the released version is `1.0.0`. The tag will be `v1.0.0`.
+
+### When a production submission finishes
+
+For cases where you anticipate sending more than one build to the store, we also allow tagging each submission that actually went to the store. So in a single release, if you first partially release 1.0.0 to the production track on Play Store, and then land a patch fix and release 1.0.1 to 100%, you will get two tags: `v1.0.0` and `v1.0.1` against the appropriate commits.
+
+## Create VCS release
+
+:::tip
+VCS releases are created at the [end of a release](#end-of-a-release).
+:::
+
+If you're using the [GitHub integration](/integrations/version-control/github) for version control, Tramline will automatically create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with an auto-generated changelog.
+
+## Pick the correct version for hotfixes
+
+When you start a [hotfix release](/using-tramline/special-cases/hotfix), Tramline will automatically pick the correct version to be hotfix'd (the last completed release). When the hotfix release starts, and if there's a diff — between the current hotfix changes and the last release — the release will jump straight into to creating a new Release Candidate build and will skip Internal builds to save time.
+
+## Start releases on a schedule
+
+:::info
+Add a schedule to your release in the [release train settings](/using-tramline/release-management/release-settings).
+:::
+
+[Scheduled releases](/using-tramline/release-management/scheduled-release) automatically start a new release on the specified date and retain the schedule for subsequent releases. You can also optionally set a scheduled release to automatically stop on failure.
+
+Additionally, if your release spans across a future release, the future release gets automatically adjusted.
+
+![](/img/scheduled-release.png)
+
+## Update Export Compliance Information in App Store Connect
+
+If enabled, Tramline will automatically sets the `usesNonExemptEncryption` to be `false` for all builds as they get upload to the App Store.
+
+## Upload builds to Tramline
+
+By default, all builds generated by your CI workflows as artifacts are automatically uploaded to Tramline. This is true for the following file types: `aab`, `apk` and `ipa`. They are subsequently also available for download from the [Tramline dashboard](/using-tramline/working-pane/stability) and [Slack notifications](/using-tramline/working-pane/stability#notifications).
+
+## Default release notes from last release
+
+Tramline will automatically apply "What's new" text or release notes from your previous release version to populate the release notes for the current release.
+
+Additionally, if you manually add new locales for your release notes directly on the stores, Tramline will automatically pull them up in the next release.
+
+## Pull Requests
+
+:::tip
+Pull requests are created under a variety of circumstances ([see above](/automations)).
+:::
 
-This ensures that all the users and stakeholders of all the relevant build channels are kept up-to-date on new changes without requiring manually sharing builds around. This is especially handy when the app is being QA'd (internally or externally) via the review steps.
+There are a few default automatic settings for all pull requests created by Tramline:
 
-<!-- TODO ## Storing builds -->
-<!-- TODO ## Patching up metadata on App Store -->
+ * If the PR is on the [GitHub VCS integration](/integrations/version-control/github), Tramline will try to set the [auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) option (if possible).
+ * Even if auto-merge flag is not possible (eg. other VCS integrations), Tramline will continually try to auto-merge until all the checks pass.
+ * For [cherry-pick PRs](#continuously-cherry-pick-commits) (or "patch" PRs), Tramline will reference-tag the name of the author of the cherry-pick commit in the body of the PR.