Contributing Guide



How to help

We welcome your contributions and participation! If you aren’t sure what to expect, here are some norms for our project so you feel more comfortable with how things will go.

If this is your first contribution to Porter, we have a tutorial that walks you through how to setup your developer environment, make a change and test it.

Code of Conduct

The Porter community is governed by our Code of Conduct. This includes but isn’t limited to: the porter and related mixin repositories, slack, interactions on social media, project meetings, conferences and meetups.

Find an issue

We have good first issues for new contributors and help wanted issues for our other contributors. When you have been contributing for a while, take a look at the “Backlog” column on our project board for high priority issues. The project board is at the organization level, so it contains issues from across all of the Porter repositories.

  • good first issues has extra information to help you make your first contribution.
  • help wanted are issues suitable for someone who isn’t a core maintainer.
  • hmm πŸ›‘πŸ€” issues should be avoided. They are not ready to be worked on yet because they are not finished being designed or we aren’t sure if we want the feature, etc.

Maintainers will do our best regularly make new issues for you to solve and then help out as you work on them. πŸ’–

We have a roadmap that will give you a good idea of the larger features that we are working on right now. That may help you decide what you would like to work on after you have tackled an issue or two to learn how to contribute to Porter. If you have a big idea for Porter, learn how to propose a change to Porter.

Another great way to contribute is to create a mixin! You can start use the Porter Skeletor repository as a template to start, along with the Mixin Developer Guide.

When you create your first pull request, add your name to the bottom of our Contributors list. Thank you for making Porter better! πŸ™‡β€β™€οΈ

When to open a pull request

It’s OK to submit a PR directly for problems such as misspellings or other things where the motivation/problem is unambiguous.

If there isn’t an issue for your PR, please make an issue first and explain the problem or motivation for the change you are proposing. When the solution isn’t straightforward, for example “Implement missing command X”, then also outline your proposed solution. Your PR will go smoother if the solution is agreed upon before you’ve spent a lot of time implementing it.

Since Porter is a CLI, the “solution” will usually look like this:

$ porter newcommand [OPTIONAL] [--someflag VALUE]
example output

How to test your pull request

We recommend running the following every time:

make verify build test-unit

If your test modified anything related to running a bundle, also run:

make test-integration

If you want to know all the targets that the CI runs, look at <build/azure-pipelines.pr-automatic.yml>.

How to get your pull request reviewed fast

🚧 If you aren’t done yet, create a draft pull request or put WIP in the title so that reviewers wait for you to finish before commenting.

1️⃣ Limit your pull request to a single task. Don’t tackle multiple unrelated things, especially refactoring. If you need large refactoring for your change, chat with a maintainer first, then do it in a separate PR first without any functionality changes.

🎳 Group related changes into commits will help us out a bunch when reviewing! For example, when you change dependencies and check in vendor, do that in a separate commit.

πŸ˜… Make requested changes in new commits. Please don’t ammend or rebase commits that we have already reviewed. When your pull request is ready to merge, you can rebase your commits yourself, or we can squash when we merge. Just let us know what you are more comfortable with.

πŸš€ We encourage follow-on PRs and a reviewer may let you know in their comment if it is okay for their suggestion to be done in a follow-on PR. You can decide to make the change in the current PR immediately, or agree to tackle it in a reasonable amount of time in a subsequent pull request. If you can’t get to it soon, please create an issue and link to it from the pull request comment so that we don’t collectively forget.

Signing your commits

You can automatically sign your commits to meet the DCO requirement for this project by running the following command: make setup-dco.

Licensing is important to open source projects. It provides some assurances that the software will continue to be available based under the terms that the author(s) desired. We require that contributors sign off on commits submitted to our project’s repositories. The Developer Certificate of Origin (DCO) is a way to certify that you wrote and have the right to contribute the code you are submitting to the project.

You sign-off by adding the following to your commit messages:

Author: Your Name <your.name@example.com>
Date:   Thu Feb 2 11:41:15 2018 -0800
This is my commit message

Signed-off-by: Your Name &lt;your.name@example.com&gt;

Notice the Author and Signed-off-by lines match. If they don’t, the PR will be rejected by the automated DCO check.

Git has a -s command line option to do this automatically:

git commit -s -m 'This is my commit message'

If you forgot to do this and have not yet pushed your changes to the remote repository, you can amend your commit with the sign-off by running

git commit --amend -s

The life of a pull request

  1. You create a draft or WIP pull request. Reviewers will ignore it mostly unless you mention someone and ask for help. Feel free to open one and use the pull request to see if the CI passes. Once you are ready for a review, remove the WIP or click “Ready for Review” and leave a comment that it’s ready for review.

    If you create a regular pull request, a reviewer won’t wait to review it.

  2. A reviewer will assign themselves to the pull request. If you don’t see anyone assigned after 3 business days, you can leave a comment asking for a review, or ping in slack. Sometimes we have busy days, sick days, weekends and vacations, so a little patience is appreciated! πŸ™‡β€β™€οΈ

  3. The reviewer will leave feedback.

    • nits: These are suggestions that you may decide incorporate into your pull request or not without further comment.
    • It can help to put a πŸ‘ on comments that you have implemented so that you can keep track.
    • It is okay to clarify if you are being told to make a change or if it is a suggestion.
  4. After you have made the changes (in new commits please!), leave a comment. If 3 business days go by with no review, it is okay to bump.

  5. When a pull request has been approved, the reviewer will squash and merge your commits. If you prefer to rebase your own commits, at any time leave a comment on the pull request to let them know that.

At this point your changes are available in the canary release of Porter! After your first pull request is merged, you will be invited to the Contributors team which you may choose to accept (or not). Joining the team lets you have issues in GitHub assigned to you.

Follow-on PR

A follow-on PR is a pull request that finishes up suggestions from another pull request.

When the core of your changes are good, and it won’t hurt to do more of the changes later, our preference is to merge early, and keep working on it in a subsequent. This allows us to start testing out the changes in our canary builds, and more importantly enables other developers to immediately start building their work on top of yours.

This helps us avoid pull requests to rely on other pull requests. It also avoids pull requests that last for months, and in general we try to not let “perfect be the enemy of the good”. It’s no fun to watch your work sit in purgatory, and it kills contributor momentum.

Contribution Ladder

Our contribution ladder defines the roles and responsibilities on this project and how to participate with the goal of moving from a user to a maintainer.

Developer Tasks

Initial setup

We have a tutorial that walks you through how to setup your developer environment, make a change and test it.

Here are the key steps, if you run into trouble, the tutorial has more details:

  1. Clone this repository with git clone https://github.com/getporter/porter.git ~/go/src/get.porter.sh/porter.
  2. Run make build install from within the newly cloned repository.

If you are planning on contributing back to the project, you’ll need to fork and clone your fork. If you want to build porter from scratch, you can follow the process above and clone directly from the project.

You now have canary builds of porter and all the mixins installed.

Makefile explained

🚧 We are in the process of transitioning from make to mage.

Mage Targets

Below are the targets that have been migrated to mage. Our new contributor tutorial explains how to install mage.

Mage targets are not case-sensitive, but in our docs we use camel case to make it easier to read. You can run either mage TestE2E or mage teste2e for example.

  • TestE2E runs a small suite of end-to-end tests using the Porter CLI.

Make Targets

Below are the most common developer tasks. Run a target with make TARGET, e.g. make build.

  • build builds all binaries, porter and internal mixins.
  • build-porter-client just builds the porter client for your operating system. It does not build the porter-runtime binary. Useful when you just want to do a build and don’t remember the proper way to call go build yourself.
  • build-porter builds both the porter client and runtime. It does not clean up generated files created by packr, so you usually want to also run clean-packr.
  • install-porter installs porter from source into your home directory $(HOME)/.porter.
  • install-mixins installs the mixins from source into $(HOME)/.porter/. This is useful when you are working on the exec or kubernetes mixin.
  • install installs porter and the mixins from source into $(HOME)/.porter/.
  • test-unit runs the unit tests.
  • test-integration runs the integration tests. This requires a kubernetes cluster setup with credentials located at ~/.kube/config. Expect this to take 20 minutes.
  • docs-preview hosts the docs site. See Preview Documentation.
  • test runs all the tests.
  • clean-packr removes extra packr files that were a side-effect of the build. Normally this is run automatically but if you run into issues with packr, run this command.
  • setup-dco installs a git commit hook that automatically signsoff your commit messages per the DCO requirement.

Install mixins

When you run make build, the canary* build of mixins are automatically installed into your bin directory in the root of the repository. You can use porter mixin install NAME to install the latest released version of a mixin.

* canary = most recent successful build of the “main” branch

Plugin Debugging

If you are developing a plugin and you want to debug it follow these steps:

The plugin to be debugged should be compiled and placed in porters plugin path (e.g. in the Azure plugin case the plugin would be copied to $PORTER_HOME/plugins/azure/.

The following environment variables should be set:

PORTER_RUN_PLUGIN_IN_DEBUGGER should be set to the name of the plugin to be debugged (e.g. secrets.azure.keyvault to debug the azure secrets plugin)
PORTER_DEBUGGER_PORT should be set to the port number where the delve API will listen, if not set it defaults to 2345
PORTER_PLUGIN_WORKING_DIRECTORY should be the path to the directory containing source code for the plugin being executed.

When porter is run it will start delve and attach it to the plugin process, this exposes the delve API so that any delve client can connect to the server and debug the plugin.

Preview documentation

We use Hugo to build our documentation site, and it is hosted on Netlify. You don’t have to install Hugo locally because the preview happens inside a docker container.

  1. Run make docs-preview to start serving the docs. It will watch the file system for changes.
  2. Our make rule should open http://localhost:1313/docs to preview the site/docs.

We welcome your contribution to improve our documentation, and we hope it is an easy process! ❀️

Write a blog post

Thank you for writing a post for our blog! πŸ™‡β€β™€οΈ Here’s what you need to do to create a new blog post and then preview it:

  1. Go to /docs/content/blog and create a new file. Whatever you name the file will be the last part of the URL. For example a file named “porter-collaboration.md” will be located at https://porter.sh/blog/porter-collaboration/.

  2. At the top of the file copy and paste the frontmatter template below. The frontmatter is YAML that instucts the blogging software, Hugo, how to render the blog post.

    ---
    title: "Title of Your Blog Post in Titlecase"
    description: "SEO description of your post, displayed in search engine results."
    date: "2020-07-28"
    authorname: "Your Name"
    author: "@yourhandle" #Not used to link to github/twitter, but informally that's what people put here
    authorlink: "https://link/to/your/website" # link to your personal website, github, social media...
    authorimage: "https://link/to/your/profile/picture" # Optional, https://github.com/yourhandle.png works great
    tags: [] # Optional, look at other pages and pick tags that are already in use, e.g. ["mixins"]
    ---
    
  3. Preview the website and click “Blog” at the top right to find your blog post.

  4. When you create a pull request, look at the checks run by the pull request, and click “Details” on the netlify/porter/deploy-preview one to see a live preview of your pull request.

Our pull request preview and the live site will not show posts with a date in the future. If you don’t see your post, change the date to today’s date.

Command Documentation

Our commands are documented at https://porter.sh/cli and that documentation is generated by our CLI. You should regenerate that documentation when you change any files in cmd/porter by running make docs-gen which is run every time you run make build.

Code structure and practices

Carolyn Van Slyck gave a talk about the design of Porter, Designing Command-Line Tools People Love that you may find helpful in understanding the why’s behind its command grammar, package structure, use of dependency injection and testing strategies.

What is the general code layout?

  • cmd: go here to add a new command or flag to porter or one of the mixins in this repository
  • docs: our website
  • pkg
    • build: implements building the invocation image.
    • cache: handles the cache of bundles that have been pulled by commands like porter install --tag.
    • cnab: deals with the CNAB spec
      • cnab-to-oci: talking to an OCI registry.
      • config-adapter: converting porter.yaml to bundle.json.
      • extensions: extensions to the CNAB spec, at this point that’s just dependencies.
      • provider: the CNAB runtime, i.e. porter install.
    • config: anything related to porter.yaml and ~/.porter.
    • context: essentially dependency injection that’s needed throughout Porter, such as stdout, stderr, stdin, filesystem and command execution.
    • exec: the exec mixin
    • mixin: enums, functions and interfaces for the mixin framework.
      • feed: works with mixin atom feeds
      • provider: handles communicating with mixins
    • porter: the implementation of the porter commands. Every command in Porter has a corresponding function in here. packr
      • version: reusable library used by all the mixins for implementing their
    • templates: files that need to be compiled into the porter binary with version command.
  • scripts:
    • install: Porter installation scripts
    • setup-dco: Set up automatic DCO signoff for the developer environment
  • tests have Go-based integration tests.

Logging

Print to the Out property for informational messages and send debug messages to the Err property.

Example:

fmt.Fprintln(p.Out, "Initiating battlestar protocol")
fmt.Fprintln(p.Err, "DEBUG: loading plans from r2d2...")

Most of the structs in Porter have an embedded get.porter.sh/porter/pkg/context.Context struct. This has both Out and Err which represent stdout and stderr respectively. You should log to those instead of directly to stdout/stderr because that is how we capture output in our unit tests. That means use fmt.Fprint* instead of fmt.Print* so that you can pass in Out or Err.

Some of our commands are designed to be consumed by another tool and intermixing debug lines and the command output would make the resulting output unusable. For example, porter schema outputs a json schema and if log lines were sent to stdout as well, then the resulting json schema would be unparsable. This is why we send regular command output to Out and debug information to Err. It allows us to then run the command and see the debug output separately, like so porter schema --debug 2> err.log.

Infrastructure

This section includes overviews of infrastructure Porter relies on, mostly intended for maintainers.

CDN Setup

See the CDN Setup Doc for details on the services Porter uses to host and distribute its release binaries.