| name | pr-and-documentation-standards |
| description | Use when creating PRs, writing or editing documentation (schema descriptions, docs markdown, examples), creating or restructuring examples/, reviewing code, or adding changelog entries. |
PR and Documentation Standards
Pull Request Structure
PR Title Format
PR titles must follow Conventional Commits: fix:, feat:, chore:, doc:, test:, refactor:, ci:, etc. The subject after the colon must start with an uppercase letter.
fix: Emit warning when use_effective_fields and auto-scaling are enabled
feat: Add search deployment resource
Do not include a scope in parentheses (e.g. fix(resource/mongodbatlas_advanced_cluster): ...). The repo convention uses the bare prefix without a scope.
Separate Refactoring from Feature Changes
Avoid mixing refactoring with functional changes in the same PR. Reviewers need to clearly distinguish which changed lines are behavioral vs structural.
Changelog Entries
Add a changelog entry (.changelog/<PR_NUMBER>.txt) for:
- Bug fixes (
release-note:bug)
- New features (
release-note:enhancement)
- Breaking changes (
release-note:breaking-change)
- New resources/data sources (
release-note:new-resource / release-note:new-data-source)
- Migration guides or user-facing documentation changes
Changelog Entry Format
- Start with a verb in 3rd person singular (e.g.
Emits, Adds, Fixes, Updates)
- Do not end with punctuation
Documentation Style Guide
Consolidate Admonitions
Avoid excessive NOTE/IMPORTANT/WARNING boxes. Prefer:
- Inlining short notes into attribute descriptions.
- Combining multiple notes into a single box.
- Downgrading from IMPORTANT to NOTE when the content is informational, not action-required.
CLOUDP Ticket References
Do not include CLOUDP ticket references in user-facing documentation. Internal ticket references are acceptable in code comments only when tracking a deliberate technical decision.
Resource and Data Source Descriptions
Start data source and resource descriptions with the resource name and a clear one-line purpose:
`mongodbatlas_log_integration` provides a resource for managing log integration configurations at the project level.
Examples (examples/ directory)
The following rules are the default for new provider examples. One user journey (flow) stays a flat root with the files listed under Flat vs siblings. Two or more flows use sibling directories. Copy examples/mongodbatlas_cloud_backup_collection_restore_job/ for that layout. Read example-layout.md in this skill directory for the canonical tree, Atlas project comment, common mistakes, and exceptions.
Flat vs siblings
- One flow: Keep files at
examples/mongodbatlas_<name>/ (main.tf, variables.tf, providers.tf, versions.tf, README.md).
- Two or more flows: Use a parent
README.md (index only, no parent main.tf) plus sibling directories named for what they do.
Rules
- Use-case directories: Name each example for what it does (
snapshot_restore, pit_restore). Do not use generic singular-data-source.tf / plural-data-source.tf.
- Standalone configs: Each subdirectory is its own root module and depends only on input variables. Do not share Terraform modules across siblings. Do not use
terraform_remote_state. Document cross-example flow in the grouped README; users copy outputs into terraform.tfvars.
- Aligned intro: Each primary
.tf file starts with a one- or two-sentence comment stating the goal. Match the sibling README opening line (the first sentence after the H1, not the H1 itself).
- Grouped root README: Parent
README.md lists siblings, typical flows, and links to the product doc. Collection restore links to Restore from Selected Databases and Collections. Other resources link their own product page.
- Docs over duplication: Keep READMEs operational (prerequisites, defaults, tfvars). Link to official MongoDB docs for product limits and semantics.
- Variables: Every user-facing value is a
variable with a description. Put defaults in variables.tf and document them in the README.
- Outputs: Expose only useful post-apply values (
job_state, collection_states, discovery IDs). Place output blocks in the primary .tf file or the Terraform file for the surface they describe. Use a dedicated outputs.tf only when it makes the example easier to read. Each output has a description.
- Template docs: Never paste HCL into
templates/**/*.md.tmpl. Embed with tffile pointing at a real file under examples/, for example {{ tffile "examples/mongodbatlas_cloud_backup_collection_restore_job/snapshot_restore/main.tf" }}. Further Examples links point at sibling directories.
Provider baseline
State once, not per sibling:
- No pinned provider version.
- Empty
provider "mongodbatlas" {}. Credentials come from the environment, not from HCL. Do not set client_id, client_secret, public_key, or private_key on the provider.
- README
export examples use Service Account MONGODB_ATLAS_CLIENT_ID / MONGODB_ATLAS_CLIENT_SECRET. Prefer those. Programmatic API keys via env also work.
versions.tf sets source = "mongodb/mongodbatlas" and required_version only.
New examples use providers.tf. Leave existing provider.tf names alone.
