focalboard/mattermost-plugin/build/sync/README.md

sync

The sync tool is a proof-of-concept implementation of a tool for synchronizing mattermost plugin repositories with the mattermost-plugin-starter-template repo.

Overview

At its core the tool is just a collection of checks and actions that are executed according to a synchronization plan (see ./build/sync/plan.yml for an example). The plan defines a set of files and/or directories that need to be kept in sync between the plugin repository and the template (this repo).

For each set of paths, a set of actions to be performed is outlined. No more than one action of that set will be executed - the first one whose checks pass. Other actions are meant to act as fallbacks. The idea is to be able to e.g. overwrite a file if it has no local changes or apply a format-specific merge algorithm otherwise.

Before running each action, the tool will check if any checks are defined for that action. If there are any, they will be executed and their results examined. If all checks pass, the action will be executed. If there is a check failure, the tool will locate the next applicable action according to the plan and start over with it.

The synchronization plan can also run checks before running any actions, e.g. to check if the source and target worktrees are clean.

Running

The tool can be executed from the root of this repository with a command:

$ go run ./build/sync/main.go ./build/sync/plan.yml ../mattermost-plugin-github

(assuming mattermost-plugin-github is the target repository we want to synchronize with the source).

plan.yml

The plan.yml file (located in build/sync/plan.yml) consists of two parts:

• checks
• actions

The checks section defines tests to run before executing the plan itself. Currently the only available such check is repo_is_clean defined as:

type: repo_is_clean
params:
  repo: source

The repo parameter takes one of two values:

• source - the mattermost-plugin-starter-template repository
• target - the repository of the plugin being updated.

The actions section defines actions to be run as part of the synchronization. Each entry in this section has the form:

paths:
  - path1
  - path2
actions:
  - type: action_type
    params:
      action_parameter: value
    conditions:
      - type: check_type
        params:
          check_parameter: value

paths is a list of file or directory paths (relative to the root of the repository) synchronization should be performed on.

Each action in the actions section is defined by its type. Currently supported action types are:

• overwrite_file - overwrite the specified file in the target repository with the file in the source repository.
• overwrite_directory - overwrite a directory.

Both actions accept a parameter called create which determines if the file or directory should be created if it does not exist in the target repository.

The conditions part of an action definition defines tests that need to pass for the action to be run. Available checks are:

• exists
• file_unaltered

The exists check takes a single parameter - repo (referencing either the source or target repository) and it passes only if the file or directory the action is about to be run on exists. If the repo parameter is not specified, it will default to target.

The file_unaltered check is only applicable to file paths. It passes if the file has not been altered - i.e. it is identical to some version of that same file in the reference repository (usually source). This check takes two parameters:

• in - repository to check the file in, default target
• compared-to - repository to check the file against, default source.

When multiple actions are specified for a set of paths, the sync tool will only execute a single action for each path. The first action in the list, whose conditions are all satisfied will be executed.

If an acton fails due to an error, the synchronization run will be aborted.

Caveat emptor

This is a very basic proof-of-concept and there are many things that should be improved/implemented: (in no specific order)

1. Format-specific merge actions for go.mod, go.sum, webapp/package.json and other files should be implemented.
2. Better logging should be implemented.
3. Handling action dependencies should be investigated. e.g. if the build directory is overwritten, that will in some cases mean that the go.mod file also needs to be updated.
4. Storing the tree-hash of the template repository that the plugin was synchronized with would allow improving the performance of the tool by restricting the search space when examining if a file has been altered in the plugin repository.