build: change the release and staging branching model (#1042)

This pull request refactors the current branching model to improve development and address several challenges associated with using staging as the default base branch for pull requests. With this update, main will serve as the base branch for pull requests, containing active development changes, while releases will be triggered upon merging pull requests into the newly created release branch.

Signed-off-by: behnazh-w <[email protected]>

Author: behnazh-w

.github/dependabot.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # This configuration file enables Dependabot version updates.
@@ -16,7 +16,7 @@ updates:
     prefix-development: chore
     include: scope
   open-pull-requests-limit: 13
-  target-branch: staging
+  target-branch: main
   # Add additional reviewers for PRs opened by Dependabot. For more information, see:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers
   # reviewers:
@@ -31,7 +31,7 @@ updates:
     prefix-development: chore
     include: scope
   open-pull-requests-limit: 13
-  target-branch: staging
+  target-branch: main
   # Add additional reviewers for PRs opened by Dependabot. For more information, see:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers
   # reviewers:
@@ -46,7 +46,7 @@ updates:
     prefix-development: chore
     include: scope
   open-pull-requests-limit: 13
-  target-branch: staging
+  target-branch: main
   # Add additional reviewers for PRs opened by Dependabot. For more information, see:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers
   # reviewers:

.github/pull_request_template.md

@@ -7,7 +7,6 @@
 - [ ] My PR title and commits follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) convention.
 - [ ] My commits include the "Signed-off-by" line.
 - [ ] I have signed my commits following the instructions provided by [GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). Note that we run [GitHub's commit verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) tool to check the commit signatures. A green `verified` label should appear next to **all** of your commits on GitHub.
-- [ ] I have selected `staging` as the base branch for my PR.
 - [ ] I have updated the relevant documentation, if applicable.
 - [ ] I have tested my changes and verified they work as expected.
 - [ ] I have referenced the issue(s) this pull request solves.

.github/workflows/_generate-rebase.yaml

@@ -1,7 +1,7 @@
-# Copyright (c) 2023 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2023 - 2025, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
-# Automatically rebase one staging branch on top of main after a new package version was published.
+# Automatically rebase main branch on top of release after a new package version is published.
 
 name: Rebase branch
 on:

.github/workflows/codeql-analysis.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # Run CodeQL over the package. For more configuration options see codeql/codeql-config.yaml
@@ -9,11 +9,11 @@ on:
   push:
     branches:
     - main
-    - staging
+    - release
   pull_request:
     branches:
     - main
-    - staging
+    - release
   schedule:
   - cron: 20 15 * * 3
 permissions:

.github/workflows/release.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # We run checks on pushing to the specified branches.
@@ -9,7 +9,7 @@ on:
   push:
     branches:
     - main
-    - staging
+    - release
 permissions:
   contents: read
 env:
@@ -28,11 +28,11 @@ jobs:
       contents: read
       packages: read
 
-  # On pushes to the 'main' branch create a new release by bumping the version
+  # On pushes to the 'release' branch create a new release by bumping the version
   # and generating a change log. That's the new bump commit and associated tag.
   bump:
     needs: check
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/release'
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -72,26 +72,26 @@ jobs:
         git push
         git push --tags
 
-  # After the bump commit was pushed to the main branch, rebase the staging branch
-  # (to_head argument) on top of the new main branch (from_base argument), to keep
+  # After the bump commit was pushed to the release branch, rebase the main branch
+  # (to_head argument) on top of the release branch (from_base argument), to keep
   # the histories of both branches in sync.
-  rebase_staging:
+  rebase_main:
     needs: [bump]
-    name: Rebase staging branch on main
+    name: Rebase main branch on release
     uses: ./.github/workflows/_generate-rebase.yaml
     permissions:
       contents: read
     with:
-      to_head: staging
-      from_base: origin/main
+      to_head: main
+      from_base: origin/release
       git_user_name: behnazh-w
       git_user_email: [email protected]
     secrets:
       REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
 
   # When triggered by the version bump commit, build the package and publish the release artifacts.
   build:
-    if: github.ref == 'refs/heads/main' && startsWith(github.event.commits[0].message, 'bump:')
+    if: github.ref == 'refs/heads/release' && startsWith(github.event.commits[0].message, 'bump:')
     uses: ./.github/workflows/_build.yaml
     permissions:
       contents: read

CONTRIBUTING.md

@@ -35,13 +35,13 @@ See our [Macaron Style Guide](./docs/source/pages/developers_guide/style_guide.r
 
 1. Ensure there is an issue created to track and discuss the fix or enhancement
    you intend to submit.
-2. Fork this repository including the `staging` branch. In Macaron, the `staging` branch is the active development branch and contains the most recent changes.
-3. Create a branch in your fork to implement the changes.  Make sure to create your branch from the `staging` branch and not `main`. We recommend using the issue number as part of your branch name, e.g. `1234-fixes`.
+2. Fork this repository.
+3. Create a branch in your fork to implement the changes. We recommend using the issue number as part of your branch name, e.g. `1234-fixes`.
 4. The title of the PR should follow the convention of [commit messages](#commit-messages).
 5. Ensure that any documentation is updated with the changes that are required by your change.
 6. Ensure that any samples are updated if the base image has been changed.
 7. Submit the pull request. *Do not leave the pull request blank*. Explain exactly what your changes are meant to do and provide simple steps on how to validate. your changes. Ensure that you reference the issue you created as well.
-8. Choose `staging` as the base branch for your PR.
+8. Choose `main` as the base branch for your PR.
 9. We will assign the pull request to 2-3 people for review before it is merged.
 
 ### Commit messages
@@ -74,7 +74,7 @@ a detailed commit message body is preferred. Make sure to keep the `Signed-off-b
 
 ## Branching model
 
-* The `main` branch is only used for releases and the `staging` branch is used for development. We only merge to `main` when we want to create a new release for Macaron.
+* The `main` branch should be used as the base branch for pull requests. The `release` branch is designated for releases and should only be merged into when creating a new release for Macaron.
 
 ## Setting up the development environment
 

docs/source/pages/installation.rst

@@ -27,7 +27,7 @@ Macaron is currently distributed as a Docker image. We provide a bash script ``r
 
 .. note:: When run, Macaron will create output files inside the current directory where ``run_macaron.sh`` is run. If you run Docker Desktop, please make sure that the current directory is bind mountable for Docker (see the `File Sharing settings <https://docs.docker.com/desktop/settings/mac/?uuid=95C3E343-F11C-4A35-A10C-6B5431B73E14#file-sharing>`_).
 
-Download the ``run_macaron.sh`` script and make it executable by running the commands (replace ``tag`` with the version you want or ``main`` for the latest version):
+Download the ``run_macaron.sh`` script and make it executable by running the commands (replace ``tag`` with the version you want or ``release`` for the latest version):
 
 .. code-block:: shell
 

docs/source/pages/tutorials/detect_malicious_java_dep.rst

@@ -202,7 +202,7 @@ And the following relation is declared in this policy:
 * ``violating_dependencies(parent: number)``
 
 Feel free to browse through the available
-relations `here <https://github.com/oracle/macaron/blob/main/src/macaron/policy_engine/prelude/>`_
+relations `here <https://github.com/oracle/macaron/blob/release/src/macaron/policy_engine/prelude/>`_
 to see how they are constructed before moving on.
 
 .. code-block:: prolog

docs/source/pages/tutorials/use_verification_summary_attestation.rst

@@ -121,7 +121,7 @@ Here is a pretty-printed version of the policy as it appears in the VSA, along w
 
     * Applying the Policy (``apply_policy_to``): To apply the ``gcn_provenance_policy``, Macaron first determines if the ``component_id`` is a valid component and if its ``PURL`` conforms to the pattern defined in the ``match`` predicate. If both conditions are met, the policy is applied.
 
-    * The template Datalog policy file can be downloaded from `here <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/policy.dl.template>`_
+    * The template Datalog policy file can be downloaded from `here <https://github.com/oracle/macaron/tree/release/src/macaron/resources/policies/gdk/policy.dl.template>`_
 
     Below you can find the template CUE file that has been used by the :ref:`mcn_provenance_expectation_1 <checks>` check at verification time to verify the provenance. It contains place holders for expected values that are populated by the GDK maintainers.
 
@@ -148,7 +148,7 @@ Here is a pretty-printed version of the policy as it appears in the VSA, along w
 
     * ``projecturl: "https://<REPO_URL>"``: This checks that the ``projecturl`` attribute exactly matches the expected Repository URL. ``<REPO_URL>`` is a placeholder for the actual repository URL, e.g., ``internal.repo.com/micronaut-projects/micronaut-core``.
 
-    * The template CUE expectation can be downloaded from `this location <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/expectation.cue.template>`_.
+    * The template CUE expectation can be downloaded from `this location <https://github.com/oracle/macaron/tree/release/src/macaron/resources/policies/gdk/expectation.cue.template>`_.
 
 
 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
@@ -175,7 +175,7 @@ Download the check_vsa.sh script
 
 .. code-block:: shell
 
-    curl -O https://raw.githubusercontent.com/oracle/macaron/main/scripts/release_scripts/check_vsa.sh
+    curl -O https://raw.githubusercontent.com/oracle/macaron/release/scripts/release_scripts/check_vsa.sh
 
 ++++++++++++++++++++++++++
 Make the script executable