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.
This project follows Google's Open Source Community Guidelines as well as the included Code of Conduct.
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 PR to modify the OpenAPI description.
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.
There are two ways you can setup your Emblem instance:
- Maximize automation by following the Emblem Quickstart
- Make the minimal steps manually:
See Testing Emblem for detailed testing instructions.
Significant changes to the architecture, developer experience, or dependencies involve making critical decisions about future design needs.
As the project evolves, we want to capture the context of these key decisions to facilitate future engineering. Please add a decision record to your pull request.
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)
The following automated checks are run against every Pull Request:
- 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 fmton all Terraform configuration. - style-python: Runs
blackon all python code. - block-merge: Blocks merging PRs that
have the
do not mergelabel, or a label containing the word "needs". - auto-label: Adds PR labels based on PR title and changed files
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.)
Emblem operates using a Trunk-Based Development model.
Larger-scale changes to Emblem should be prototyped in the /experimental folder.
They can then be merged into the main branch in a single pass.