Skip to content

Latest commit

 

History

History
172 lines (120 loc) · 8.4 KB

CONTRIBUTING.md

File metadata and controls

172 lines (120 loc) · 8.4 KB
Raw

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Want to get more involved with the upstream Peribolos community? Take a look at their repository!

Issues

We'd love you to open issues, if they're relevant to this repository: feature requests, bug reports, questions about our processes, declarations of gratefulness, etc. are all welcome.

In particular, if you have a large PR you want to send our way, it may make sense to open an issue to discuss it with the maintainers first.

We also use the label 'help wanted' to show issues we want help on! If you'd like to get started working in this repository, it'd be best to jump into those issues. View those issues here!

Submitting a pull request

  1. Fork and clone the repository
  2. Make your changes
  3. Push to your fork and submit a pull request
  4. Pat your self on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Install and use pre-commit to follow the same code style and conventions.
  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
  • Write a good commit message, please use conventional commits

Work in Progress pull request are also welcome to get feedback early on, or if there is something blocked you. Please open such pull requests as Draft.

Merging the Pull Request & releasing a new version

Releases are automated using semantic-release. The following commit message conventions determine which version is released, see conventional commits for more details:

  1. fix: ... or fix(scope name): ... prefix in subject: bumps fix version, e.g. 1.2.3 → 1.2.4
  2. feat: ... or feat(scope name): ... prefix in subject: bumps feature version, e.g. 1.2.3 → 1.3.0
  3. BREAKING CHANGE: in body: bumps breaking version, e.g. 1.2.3 → 2.0.0

Only one version number is bumped at a time, the highest version change trumps the others. Besides publishing a new version to package.json, semantic-release also creates a git tag and release on GitHub, generates changelogs from the commit messages and puts them into the release notes. Semantic release is part of a larger workflow which also handles container builds for each image and pushes corresponding tags to image repository.

New container images are created from the following references:

  1. main: Each commit is published as container image to quay using the @latest image tag
  2. v<version>: For example v1.2.3 tag. New versions are published to quay using the @v<version> (e.g. @v1.2.3.) image tag

Development setup

The application is a Github app. For development, the developers have to replicate the same flow as Github App.

Set Environment

The environment variable can be set:

  1. In the .env file for local setup.
  2. In the secrets manifests for cluster setup.

Required Environment variables: APP_ID and PRIVATE_KEY Other Environment variable: WEBHOOK_PROXY_URL and WEBHOOK_SECRET Example: .env.example Reference: docs

Methods of developments

Run locally

  1. It's crucial your node version matches the one installed in the container deployment. Using different version can make any packages installed in your development unusable when built into a container image. Please install NVM and set it up for NodeJS v16:

    # Install currently locked version from .nvmrc
nvm install
# Use this version
nvm use

    Note: nvm use can be called automatically by your shell on entering the directory, see docs on NVM or use a plugin like oh-my-zsh nvm

  2. Remember to set environment variables via .env file. We require:

    • WEBHOOK_PROXY_URL (use https://smee.io/ to obtain it, and set it in your GitHub Application config)
    • APP_ID matching your GitHub Application config
    • Optionally you should also set PRIVATE_KEY if your app's private key is located outside of the repository directory, see Probot documentation for more details

Note: If you are having issues using https://smee.io , you can also deploy your own instance of smee. We provide deployment artifacts for your own smee deployment within the ./manifests/smee directory. For example in Openshift, simply run oc apply -k manifests/smee -n <your-smee-namespace> to set up a quick deployment.

  1. Run the app

    # Install dependencies
npm install --include=dev

# Run local instance with hot reloading
npm run dev

Run locally as a container

# 1. Run supplied script which will create image
./scripts/build-image.sh

# 2. Start container
podman run -e APP_ID=<app-id> -e PRIVATE_KEY=<pem-value> peribolos-as-a-service

Run in a Kubernetes cluster

One can use the deployment manifest, provided here To deploy the app in an openshift/k8s cluster.

Then create a custom image of the dev work and swap the image in deployment with it. There are two ways to do this:

  1. Create a custom image by yourself and push it to the registry.

    ./scripts/build-image.sh
podman login quay.io
podman push localhost/peribolos-as-a-service <quay repo>

  2. Update dev overlay to point to your image and deploy to a connected cluster

    pushd manifests/overlays/dev
kustomize edit set image quay.io/open-services-group/peribolos-as-a-service=<quay repo>
popd

kustomize build manifests/overlays/dev | kubectl apply -f -

Use the route URL from the openshift routes in the webhook setup.

Provide Webhooks

The App requires a webhook payload of the GitHub application. Developer can utilize different methods to provide the webhook payload:

  • Provide Direct Github app webhook payload:
    • Setup a Github App Under your Github user.
      • Goto your Github user setting > Developer Settings Reference: Github Docs
      • Create a new github app:
        • Fill in name and other details
        • For Webhook URL use the url setup in the section
        • Select permission required for development
        • Note: At the end, select the app for your account to keep it simple.
      • Once app is created, create the client secret for authentication.
      • Install it on one repo or on your whole account.
      • Triggered Webhook can be viewed under Advance section of the app.
  • Simulate Github app webhook payload:
    • Provide payload from test/fixtures, where different payloads pertaining to different github event can be stored.
      • Payload from fixture can be simulated via probot. Reference: docs
      • Test suites can also be used. Reference: docs

Resources