@elliemae/scmutil

Source Control Management Utilities

Follows GIT Guidelines & Conventional Commit Guidelines

Features

• Release Notes creation
• Tagging release with Calendar Versioning Scheme or Semantic Versioning scheme
• Release Creation in SCM (GitHub) along with release notes creation
• Writes list of contributors worked on a release as json

Dependencies

• NodeJS >= 16.x
• local checked out branch name should match the github upstream branch name

Usage

npm i -g @elliemae/scmutil

Environment Variablese

Following are required environment variables for comands that nees to connect to github,

• GH_USERNAME - github username that has write permissions to the Github repo
• GITHUB_TOKEN - OAuth token of a user account that has write permissions to the Github repos
• BRANCH_NAME - Github repo branch that needs to be released

following are optional and

• MODULE_NAME - override the module name displyed in the slack markdown. default: git repo name
• GIT_REMOTE - name of the git remote. if not provided, 'origin' will be used
• GITHUB_URL - base url of the GitHub server. if not provided, base url will be gathered from git remote url
• GITHUB_REPO_OWNER - name of the GitHub repo owner. if not provided, owner information in the git remote url will be used
• GITHUB_REPO - name of the GitHub repo. if not provided, repo information in the git remote url will be used
• LOG_LEVEL - override default log level of this tool. choices: "debug", "info", "warn", "error" default: "info"
• LOCAL_REPO_PATH - absolute path to the local repo folder

CLI

scmutil [command]

Commands:
  scmutil get <command>         Get details from SCM
  scmutil merge <src> <target>  Auto merges source branch with target branch and
                               creates Pull Request in Github
  scmutil release               Prepares Release Notes, Tags releaes, Creates
                               Github Release and Uploads assets to the release
                               tag

Options:
  --help  Show help                                                    [boolean]

Examples:
  scmutil get outdated
  scmutil get contributors
  scmutil get releases
  scmutil get slack-release-notes
  scmutil release --version 20.0.1 --format calver --assets dist.zip
  source.zip
  scmutil merge develop release/21.1.0

Release Application / Library

scmutil release

Prepares Release Notes, Tags releaes, Creates Github Release and Uploads assets
to the release tag

Options:
  --help               Show help                                       [boolean]
  --version, -v        release version. format: YY.QUARTER.PATCH e.g: 20.1.0
                                                             [string] [required]
  --format, -f         choose a versioning format
                               [choices: "calver", "semver"] [default: "calver"]
  --assets             Assets to be attached to the Github release. e.g:
                       dist.zip source.zip                 [array] [default: ""]
  --prerelease, --pre  identify the release as a prerelease
                                                    [boolean] [default: "false"]
  --logLevel           log level
                   [choices: "debug", "info", "warn", "error"] [default: "info"]
Examples:
  scmutil release --version 20.0.1 --format calver --assets dist.zip
  source.zip

Get Contributors

scmutil get contributors

Collect list of authors and committers worked on the latest release and writes to
a JSON file

Options:
  --help      Show help                                                [boolean]
  --logLevel  log level
                   [choices: "debug", "info", "warn", "error"] [default: "info"]

Get Release Details

scmutil get releases

get releases of a scm repository

Options:
  --help      Show help                                                [boolean]
  --last      get last release name                                    [boolean]
  --logLevel  log level
                   [choices: "debug", "info", "warn", "error"] [default: "info"]

Get Release Notes as Slack Markdown

scmutil get slack-release-notes

get release note of last GitHub release and format for slack

Options:
  --help      Show help                                                [boolean]
  --name      release name                                [string] [default: ""]
  --logLevel  log level
                   [choices: "debug", "info", "warn", "error"] [default: "info"]

Merge Branches

scmutil merge <src> <target>

Auto merges source branch with target branch and creates Pull Request in Github

Positionals:
  src     source branch name                                 [string] [required]
  target  target branch name                                 [string] [required]

Options:
  --help      Show help                                                [boolean]
  --dryrun    skips creating Pull Request in Github    [boolean] [default: true]
  --logLevel  log level
                   [choices: "debug", "info", "warn", "error"] [default: "info"]

Development

• clone the repo
• npm run setup

Test

• npm run test

FAQ

• Can I ignore files from merge?

  Yes. create a .gitpathspec file in your repo root and list file(s) that you want to ignore during merge. Separate each line using LF. You can use glob patterns to select multiple files.

  sample .gitpathsepc file given below. This file ignores merge for all markdown files in the repo, package.json in the root of the repo and ci_cd/jenkinsfile.

  **/*.md
  ci_cd/jenkinsfile
  package.json
  

• Can I specify merge strategy when there are merge conflicts?

  Yes. Add the file(s) to .gitattributes (in root of your repo) and specify one of the below strategies. Glob patterns are allowed

  • merge=ours choose current branch changes during conflict
  • merge=theirs choose incoming branch changes during conflict

  sample .gitattributes file contnet below

  **/CHANGELOG.md merge=ours
  **/package.json merge=theirs
  README.md merge=ours
  ci_cd/jenkinsfile merge=ours