Skip to content
This repository has been archived by the owner on Jul 25, 2024. It is now read-only.

Latest commit

 

History

History
158 lines (120 loc) · 6.94 KB

CONTRIBUTING.md

File metadata and controls

158 lines (120 loc) · 6.94 KB
Raw

Contributing guide

Thank you for your interest in contributing to Emblem! Please review this guide for important information before contributing to the project.

Before you begin

Sign our Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Review our Community Guidelines

This project follows Google's Open Source Community Guidelines as well as the included Code of Conduct.

Where to begin

Contributors can browse issues labeled Help Wanted.
Issues labeled Good First Issues are recommended for new contributors.

Submitting GitHub issues

We welcome all contributors to open GitHub issues in the repository for bugs, feature requests, and issues. Please use the provided issue templates when submitting issues and include log files and error output when applicable.

Pull requests

Submitting a PR

When submitting a PR, please provide a summary in the PR description of what changes are being made and the expected impact. Be sure to include any GitHub issues associated with the request and any other context that will be helpful for review.

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

We recommend making suggestions to a Pull Request to collaboratively fix problems.

User journeys

We represent business requirements as "User Journeys". Each user journey may represent a new use case for the application, an operational requirement for the architecture, or a demo requirement for how this application is used as a learning resource.

Journeys should be created via the User Journey Proposal template.

For more incremental changes, please open a feature request. Referencing an existing User Journey is helpful in considering how it fits project scope.

The first implementation step for any API change is to send a PR to modify the OpenAPI description.

Github workflows automation

All pull requests are subject to the following automated checks where applicable:

  • cla/google: Ensure Google's Contributor License Agreement has been met for the proposed change.
  • header-check: Ensure all applicable files have copyright headers.
  • style-terraform: Runs terraform fmt on all Terraform configuration.
  • style-python: Runs black on all python code.
  • block-merge: Blocks merging PRs that have the do not merge label, or a label containing the word "needs".
  • auto-label: Adds PR labels based on PR title and changed files

Design and project philosophy

Decision records for significant changes

Significant changes to the architecture, developer experience, or dependencies involve making critical decisions about future design needs.

As the project evolves, we capture these key decisions in architectural decision records. These decision records facilitate future engineering and provide developers with valuable historical context around some of the major technical components of Emblem.

See docs/decisions for more information.

Positive and helpful feedback

Whether it's a code review, a static analysis outcome, or an error message in the app, our goal is to enable contributor and user success.

  • Warnings & errors should provide context, suggest next steps, and provide direct access to more details. (For example, link to build logs.)
  • When a warning or error has a generally agreed fix or next step, point the way or suggest the fix. (For example, linting checks on a PR should propose the fixes to correct the code formatting.)

Toil automation

If you plan to automate codebase quality checks, consider using googleapis/code-suggester to suggest changes. Minimizing developer follow-up action is helpful!

If no Google Cloud resources are needed, use GitHub Actions to drive automation. Otherwise use Cloud Build (decision).

Infrastructure (including test fixtures) should be managed automatically. This should be by Terraform where possible, and by custom scripts where necessary. (decision) However, some cases exist where resources cannot be managed automatically. In those cases, Emblem allows for manual resource management (decision).