Skip to content

Latest commit

 

History

History
151 lines (110 loc) · 5.12 KB

CONTRIBUTING.md

File metadata and controls

151 lines (110 loc) · 5.12 KB
Raw

Contributing to Summon

Thanks for your interest in Summon!

For general contribution and community guidelines, please see the community repo. In particular, before contributing please review our contributor licensing guide to ensure your contribution is compliant with our contributor license agreements.

Development

Building and packaging

To build versions for Linux, macOS and Windows:

./build --snapshot

Binaries will be placed in dist/goreleaser.

Running the project from source

Run the project with:

go run cmd/main.go

Unit Testing

Run tests with go test -v ./... or ./test (for CI).

Smoke Testing

Smoke testing is used to verify that the output generated by our ./build script functions as expected.

This is done through running the generated binaries against production or custom providers and verifying the output manually.

Generating Mock Providers

For testing purposes, it is often necessary to create a "mock" provider which can verify input and output. This can be done by creating a script which can be run by Summon and placing it in the default path, /usr/local/lib/summon/

For example, we can create a provider that simply returns the literal variable that is passed into it:

  1. Create a shell script in your Summon path called mock:
$ echo '#!/bin/bash -e \n echo "$@"' > /usr/local/lib/summon/mock
  1. Make your new script executable
$ sudo chmod +x /usr/local/lib/summon/mock
  1. Use your 'provider' with the following command
$ summon -p mock --yaml 'FOO: !var bar' /bin/bash -ec 'echo $FOO'
bar

This mock provider can then be used against locally generated binaries or the source itself, as needed.

Releasing

Releases should be created by maintainers only. To create a tag and release, follow the instructions in this section.

Pre-requisites

  1. Review the git log and ensure the changelog contains all relevant recent changes with references to GitHub issues or PRs, if possible.
  2. Ensure that all documentation that needs to be written has been written by TW, approved by PO/Engineer, and pushed to the forward-facing documentation.

Update the changelog and notices (if necessary)

  1. Update the CHANGELOG.md file with the new version and the changes that are included in the release.

  2. Update NOTICES.txt

    go install github.com/google/go-licenses@latest

# Verify that dependencies fit into supported licenses types.
# If there is new dependency having unsupported license, that license should be
# included to notices.tpl file in order to get generated in NOTICES.txt.
$(go env GOPATH)/bin/go-licenses check ./... \
  --allowed_licenses="MIT,ISC,Apache-2.0,BSD-3-Clause,BSD-2-Clause" \
  --ignore $(go list std | awk 'NR > 1 { printf(",") } { printf("%s",$0) } END { print "" }')

# If no errors occur, proceed to generate updated NOTICES.txt
$(go env GOPATH)/bin/go-licenses report ./... \
  --template notices.tpl \
  --ignore github.com/cyberark/summon \
  --ignore $(go list std | awk 'NR > 1 { printf(",") } { printf("%s",$0) } END { print "" }') \
  > NOTICES.txt

Release and Promote

  • Merging into main/master branches will automatically trigger a release. If successful, this release can be promoted at a later time.
  • Jenkins build parameters can be utilized to promote a successful release or manually trigger aditional releases as needed.
  • Reference the internal automated release doc for releasing and promoting.

Troubleshooting

The following issues, and their respective solutions, are occasionally encountered when using Summon for the first time.

Q: When I run commands like this,

$ summon -p <provider> echo $FOO

the variable FOO appears to be empty.

A: When running Summon directly in a shell, your current shell(not Summon's shell) interprets the value of FOO before Summon does. To make sure that the variable is correctly expanded, you need to wrap your echo command with something that understands environment variables passed from summon (like bash). A working example would be:

$ summon -p <provider> /bin/bash -ec 'echo $FOO'
bar

Q: When I run commands like this,

summon -p <provider> --yaml "FOO: !var bar" /bin/bash -c 'echo $FOO'

I receive the following error:

yaml: unmarshal errors:
  line 1: cannot unmarshal !!str `FOO !va...` into map[string]yaml.Node

OR my output is empty.

A: In the first case, the ! is part of history expansion in bash. To use it in this case, the string will need to be enclosed in single quotes. In the second case, the echo statement should also be enclosed in single quotes, to avoid your current shell interpolating the variable before summon can. A working example would be:

$ summon -p <provider> --yaml 'FOO: !var bar' /bin/bash -ec 'echo $FOO'
bar