Welcome to the ProjectPlanton Contributor Guide! This guide is designed to help developers and DevOps engineers get started with contributing to ProjectPlanton. Whether you’re interested in becoming a maintainer or simply contributing code, this guide will walk you through the steps necessary to make meaningful contributions to the project.

Before you begin, it’s essential to have a basic understanding of ProjectPlanton’s goals, architecture, and components. We highly recommend watching our Restaurant Analogy video series, where we explain the core concepts of ProjectPlanton using the analogy of a restaurant.

Video Series - Restaurant Analogy

Video Series - Project-Planton Three Pillars Deep Dive

Please ensure you’ve watched these videos before proceeding.

Getting Started

Prerequisites

Before contributing to ProjectPlanton, please ensure you have the following:

• Understanding of ProjectPlanton: Watch the Restaurant Analogy video series linked above.
• Development Environment:
  • Golang: ProjectPlanton is written in Golang. Install Golang by following the official Golang installation guide.
  • Pulumi: Install Pulumi by following the Pulumi installation instructions.
  • Git: Ensure you have Git installed and configured.
  • Code Editor: We recommend using GoLand or Visual Studio Code with Go extensions.

Contributor Types

There are two primary ways to contribute to ProjectPlanton:

1. Maintainer: As a maintainer, you have direct access to the ProjectPlanton repositories. Maintainers can create branches, push changes directly, and merge pull requests.
2. Contributor: As a contributor, you can contribute by forking the repositories, creating branches in your fork, and submitting pull requests to the main repository.

The workflows for maintainers and contributors differ slightly, which we’ll explain in detail below.

Contribution Overview

ProjectPlanton consists of three core components:

1. APIs: Defined using Protocol Buffers (protobufs), the APIs specify the inputs required by the Pulumi modules.
2. Pulumi Modules: Written in Golang, these modules define the infrastructure components to be deployed.
3. CLI: Also written in Golang, the CLI provides a command-line interface for users to interact with ProjectPlanton.

Depending on your interests and expertise, you can contribute to any of these components.

Contributing as a Maintainer

If you’re a maintainer, you have direct access to the repositories and can create branches and push changes without forking.

Repository Access

• Organization: github.com/project-planton
• CLI Repository: project-planton/project-planton
• Pulumi Modules: Each Pulumi module is a separate repository within the organization, named using the pattern: project-planton/<module-name>-pulumi-module (e.g., project-planton/s3-bucket-pulumi-module).

Workflow for Maintainers

1. Clone the Repository:

   git clone git@github.com:project-planton/project-planton.git
2. Create a New Branch:

   git checkout -b <feature-or-bugfix-branch>
3. Make Changes: Modify the code as needed.
4. Test Your Changes: See the specific sections below for testing changes to the CLI, Pulumi modules, or APIs.
5. Commit and Push:

   git add .
   git commit -m "Your commit message"
   git push origin <feature-or-bugfix-branch>
6. Create a Pull Request: Open a pull request against the main branch in the repository.
7. Review and Merge: After reviews, merge the pull request.

Contributing as a Contributor

If you’re a contributor without direct access, you’ll need to fork the repository.

Workflow for Contributors

1. Fork the Repository: Click the “Fork” button on the repository’s GitHub page.
2. Clone Your Fork:

   git clone git@github.com:<your-username>/project-planton.git
3. Add Upstream Remote:

   git remote add upstream git@github.com:project-planton/project-planton.git
4. Create a New Branch:

   git checkout -b <feature-or-bugfix-branch>
5. Make Changes: Modify the code as needed.
6. Test Your Changes: See the specific sections below for testing changes to the CLI, Pulumi modules, or APIs.
7. Commit and Push:

   git add .
   git commit -m "Your commit message"
   git push origin <feature-or-bugfix-branch>
8. Create a Pull Request: Go to your fork on GitHub and create a pull request against the main branch of the original repository.
9. Address Reviews: Respond to any review comments and make necessary changes.
10. Wait for Merge: A maintainer will merge your pull request after approval.

Contributing to the CLI

Overview

The ProjectPlanton CLI is written in Golang and uses the Cobra package for command-line tools. You can contribute by improving the user experience, adding new commands, or fixing bugs.

Steps to Contribute to the CLI

1. Clone the Repository

For maintainers:

git clone git@github.com:project-planton/project-planton.git

For contributors:

git clone git@github.com:<your-username>/project-planton.git
git remote add upstream git@github.com:project-planton/project-planton.git

2. Create a New Branch

git checkout -b <your-feature-branch>

3. Make Changes

• Navigate to the cmd/project-planton directory. Each command has its own .go file.
• For example, to modify the load manifest command, edit loadManifest.go.
• Add or modify code as needed.

4. Test Your Changes

• Ensure Golang is installed.

• Run the CLI locally:

  go run main.go <your-command>

• Alternatively, you can build the binary:

  make local

  This places the binary in your local ~/bin directory.

• Test your changes by running the command:

  project-planton <your-command>

5. Commit and Push

git add .
git commit -m "Describe your changes"
git push origin <your-feature-branch>

6. Create a Pull Request

• Go to GitHub and create a pull request against the main branch.

Contributing to Pulumi Modules

Overview

Pulumi modules in ProjectPlanton define infrastructure components (deployment components). Each module corresponds to a specific resource (e.g., AWS S3 bucket, AWS VPC).

Steps to Contribute to Pulumi Modules

1. Clone the Pulumi Module Repository

For maintainers:

git clone git@github.com:project-planton/<module-name>-pulumi-module.git

For contributors:

git clone git@github.com:<your-username>/<module-name>-pulumi-module.git
git remote add upstream git@github.com:project-planton/<module-name>-pulumi-module.git

2. Create a New Branch

git checkout -b <your-feature-branch>

3. Make Changes

• Modify the Pulumi module code as needed.
• For example, you can update resource properties, fix bugs, or add new features.

4. Test Your Changes

• Set up Pulumi to use a local state file:

  pulumi login file://~/.pulumi

• Run Pulumi commands to test your module:

  pulumi up

• To use your local module instead of the one from GitHub, specify the --module flag when running the CLI:

  project-planton pulumi up --module /path/to/your/local/module

5. Commit and Push

git add .
git commit -m "Describe your changes"
git push origin <your-feature-branch>

6. Create a Pull Request

• Go to GitHub and create a pull request against the main branch.

Contributing to the APIs

Overview

ProjectPlanton uses Protocol Buffers (protobufs) to define APIs that specify the inputs required by Pulumi modules. Changes to the APIs are necessary when you need to accept new inputs or modify existing ones.

Steps to Contribute to the APIs

1. Clone the CLI Repository (APIs are co-located)

For maintainers:

git clone git@github.com:project-planton/project-planton.git

For contributors:

git clone git@github.com:<your-username>/project-planton.git
git remote add upstream git@github.com:project-planton/project-planton.git

2. Create a New Branch

git checkout -b <your-feature-branch>

3. Modify Protobuf Files

• Navigate to the apis directory within the repository.
• Find the relevant .proto file for the resource you wish to modify.
  • For example: apis/project/planton/provider/aws/vpc/spec.proto
• Add or modify fields as needed.
  • Ensure you increment the field numbers correctly.

Example:

string alias_name = 8; // This field is being added for demo purposes only.

4. Build and Generate Code

• Run the build command to generate the Go code from the protobuf definitions:

  make build

5. Update Pulumi Modules to Use New APIs

• If the changes affect Pulumi modules, you’ll need to update them as well.

• Clone the relevant Pulumi module repository.

• In the module’s go.mod file, temporarily replace the dependency to use your local version:

  replace github.com/project-planton/project-planton => /path/to/your/local/project-planton

• Update the module code to use the new API fields.

6. Test Your Changes

• Build and test the CLI with your changes:

  go run main.go <your-command>

• Ensure that the Pulumi modules work correctly with the new APIs.

7. Commit and Push

• Commit changes in both the CLI (APIs) and Pulumi module repositories.
• Push your branches to your forks or the origin.

8. Create Pull Requests

• Create pull requests for both the CLI and Pulumi module changes.
• Reference each pull request in the other for clarity.

Releasing Changes (Maintainers Only)

Releasing a New Version of the CLI

After merging changes to the main branch, you can release a new version:

1. Tag the Release:

   git tag -a vX.Y.Z -m "Release version X.Y.Z"
   git push origin vX.Y.Z

2. Create a GitHub Release: Go to GitHub and draft a new release based on the tag.

3. Update Homebrew Tap: If applicable, update the Homebrew tap to point to the new version.

Updating Pulumi Module Dependencies

• After releasing a new version of the CLI (which includes the APIs), update the Pulumi modules to use the new version.

• In the module’s go.mod file, update the dependency:

  require github.com/project-planton/project-planton vX.Y.Z

• Commit and push the changes, then create a pull request.

Conclusion

Thank you for your interest in contributing to ProjectPlanton! We appreciate your efforts to improve the project. If you have any questions or need assistance, please reach out via GitHub issues or contact one of the maintainers.