Who we are

We are the developers of Plastic SCM, a full version control stack (not a Git variant). We work on the strongest branching and merging you can find, and a core that doesn't cringe with huge binaries and repos. We also develop the GUIs, mergetools and everything needed to give you the full version control stack.

If you want to give it a try, download it from here.

We also code SemanticMerge, and the gmaster Git client.

The new Merge Rules system

Friday, September 20, 2019 María Barrios Carrasco 0 Comments

Now, you can restrict merges to happen only if certain rules are met. We call this new feature "Merge Rules" and it is available both for on-premises (Team and Enterprise) and Cloud Edition.

It is very easy to set rules like "don't allow to merge branches if they are not reviewed" and "only allow merges from child branches" among others.

Previously, you'd have to write a trigger to enforce this behavior, but now it is just a matter of setting a few merge rules.

Types of merge rules

With the Merge Rules system, you can restrict merges to certain branches, so that:

Let's see below in detail these merge rules.

How the Merge Rules system works

  1. You must first specify one or more merge rules.

    A merge rule defines:

    • If the merge rule is enabled or not
    • The affected repositories
    • A restriction:
      • The restriction includes the source and destination branches involved in the merge.
      • These branches must match a pattern.
      • The branch matching works by specifying one or more of the following filters:
        • branch name patterns (with '*' to represent any substring)
        • branch attribute names and, optionally, attribute values

        You can see is this section how filtering works.

      Let's see a merge rule example to clarify these concepts:

  2. Then, when you're about to merge a branch, the server will check whether there are any rules that apply to the involved source/destination branches pair.

'only_allow_merges_if_reviewed' rule

Definition

Only allows to merge branches if they have an approved code review. It is an equivalent to the popular "pull request restrictions" that force to review branches before merge.

Example

[{
   "enabled": true,
   "repositories": "*",
   "rule": "only_allow_merges_if_reviewed",
   "to":
   {
      "branchNames": ["main"]
   },
   "from":
   {
      "branchNames": ["QUAK-*"],
   }
}]

This (enabled) rule applies to all repositories and forces all branches named QUAK-* to be reviewed prior to be merged to main.

In the diagram below, only branch QUAK-001 will merge to main:

If a merge can't happen, you'll receive an error like this:

Cannot perform the merge. Review the branch '/main/QUAK-002' to merge it to '/main'.

'restrict_merges_to_branch' rule

Definition

Restricts merges to a given branch. This way, the merges to that branch can only come from a given set of branches.

It is possible to specify rules that apply to groups of branches too.

Example

[{
   "enabled": true,
   "repositories": "codice",
   "rule": "restrict_merges_to_branch",
   "to":
   {
     "branchNames": ["/fix3.0"],
   },
   "from":
   {
     "branchNames": ["fixes-*"],
   }
}]

In repository codice, merges to branch /fix3.0 are only allowed from branches named fixes-*. (Remember that you can use wildcards.)

In the diagram below, branches /fix-3.0/fixes-089 and /fix-3.0/fixes-090 will merge to fix-3.0:

'only_allow_merges_from_parent' rule

Definition

Only allows merges to a given branch that come from its parent.

This is very useful to enforce that certain branches only allow to be rebased from the parent, and won't accept changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams implement something very similar to restrict the flow of changes among streams.

Example

[{
   "enabled": true,
   "repositories": "game*",
   "rule": "only_allow_merges_from_parent",
   "to":
   {
     "branchNames": ["task*"],
   }
}]

In repositories named like game*, branches with name task* can only receive merges from their parent branch. This way you can prevent merges across different task branches.

In the diagram below, branch task001 will receive merges from main, and branch task003 will receive merges from dev-002:

'only_allow_merges_from_children' rule

Definition

Only allows merges to a given branch that come from its child branches.

This is very useful to enforce that certain branches only allow merges from the children, and won't accept changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams implement something very similar to restrict the flow of changes among streams.

Example

[{
   "enabled": true,
   "repositories": "game*",
   "rule": "only_allow_merges_from_children",
   "to":
   {
     "branchNames": ["iteration*"],
   }
}]

In the repositories with name game*, branches with name iteration* can only receive merges from their child branches.

In the diagram below, /main/iteration-32/task23 can be merged into /main/iteration-32, but it cannot be merged into /main/iteration-15, as it is not a child of that branch:

Filtering

To filter the branches involved in a rule, you can use the branches name, the branches attribute or both:

  • Filtering by name: Use the branchNames key to specify the branch names. For example:
    [{
        "enabled": true,
        "repositories": "game*",
    
        "rule": "only_allow_merges_if_reviewed",
        "to":
        {
            "branchNames": ["main"]
        },
        "from":
        {
            "branchNames": ["scm*"],
        }
    }]
    
  • Filtering by attribute: Use the branchesWithAttribute key to filter by attribute by specifying the attribute name and, optionally, a value. For example:
    [{
        "enabled": true,
        "repositories": "*",
    
        "rule": "only_allow_merges_if_reviewed",
        "to":
        {   
            "branchesWithAttribute": [
                {
                    "attribute": "merge_only_reviewed",
                    "value": "enabled"
                }
            ]
        },
        "from": 
        {
            "branchesWithAttribute": [
                {
                    "attribute": "task",
                }
            ]
        }
    }]
    
  • Filtering by name and attribute: Combine the above filters to filter by branch name and attribute. For example:
    [{
       "enabled": true,
       "repositories": "game*",
       "rule": "only_allow_merges_from_parent",
       "to":
       {
           "branchNames": ["scm*"],
           "branchesWithAttribute": [
               {
                   "attribute": "restricted_rebases",
                   "value": "yes"
               }
           ]
       }
    }]
    

    or:

    [{
        "enabled": true,
        "repositories": "game*",
        "rule": "only_allow_merges_if_reviewed",
        "to":
        {
            "branchesWithAttribute":
            [
                 {
                    "attribute": "merge_only_reviewed"
                 }
            ]
        },
        "from":
        {
            "branchNames": ["scm*"],
        }
    }]
    

Managing the Merge Rules

The merge rules are stored in the mergerules.conf file in the server directory (where plasticd.exe is located). This is a JSON file that contains your configured merge rules.

The merge rules in this file must to be placed inside an array [].

The following is an example of a mergerules.conf file with two merge rules:

[{
    "enabled": true,
    "repositories": "code*",

    "rule": "only_allow_merges_if_reviewed",
    "to":
    {   
        "branchNames": ["main"],
        "branchesWithAttribute": [
            {
                "attribute": "merge_only_reviewed",
                "value": "enabled"
            }
        ]
    },
    "from": 
    {
        "branchNames": ["scm*"],
        "branchesWithAttribute": [
            {
                "attribute": "task",
            }
        ]
    }
},
{
   "enabled": true,
   "repositories": "game*",

   "rule": "only_allow_merges_from_parent",
   "to":
   {
       "branchNames": ["scm*"],
       "branchesWithAttribute": [
           {
               "attribute": "restricted_rebases",
               "value": "yes"
           }
       ]
   }
}]

You will find a mergerules.conf file with some examples in your server directory, inside config_samples, and alongside the binaries for clean setups (on Windows using the installer, and GNU/Linux using the official packages) so you can directly modify it.



How can you configure your merge rules?

  • mergerules.conf:

    To configure your merge rules, you can directly edit the mergerules.conf file in your server directory.

    You don't need to restart the server for changes to take effect!
  • Merge Rules section in the WebAdmin:

    You can manage your Merge Rules from the WebAdmin. You can select and configure the ones that fit your needs best.

    You don't need to restart the server for changes to take effect!
  • Merge Rules for your cloud organization repositories:

    To configure the Merge Rules for your cloud organization repositories, go to your cloud dashboard and click the Edit Merge Rules button:

    A new dialog appears where you can manage your Merge Rules for your selected cloud repository:

Availability

We first launched the Merge Rules system in release BL3442. This first system only supported the only_allow_merges_if_reviewed rule.

But since release release BL3515, the Merge Rules system supports the four merge rules described above:

  • only_allow_merges_if_reviewed
  • restrict_merges_to_branch
  • only_allow_merges_from_parent
  • only_allow_merges_from_children

Wrapping up

The Merge Rules system lets you define what branches can be merged by following matching rules related to the affected repositories, and source and destination branches.

These rules are stored in the mergerules.conf file in the server directory (where plasticd.exe is located).

You can manage your merge rules by directly editing the mergerules.conf file or by using the Merge rules section in the WebAdmin. Remember that you can also configure merge rules for your cloud repositories.

María Barrios Carrasco
I'm in charge of the documentation area and the one to let you know the news about our products: Plastic SCM, SemanticMerge and gmaster.
I started my degree in Computer Engineering at the University of Burgos and finished my studies at the University of Valladolid.
I love doing handmade crafts, going for a walk and for tapas 😋.
You can reach me at @maria13mbc.

0 comentarios: