Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
122 lines (77 loc) · 5.37 KB

CONTRIBUTING.md

File metadata and controls

122 lines (77 loc) · 5.37 KB

Contributing to the Team API Framework

Thank you for your interest in improving this framework. We welcome contributions from everyone who wants to help teams work more effectively.

Code of conduct

This section outlines the behavioral expectations for all contributors to ensure a respectful and productive collaborative environment.

We are committed to providing a welcoming and inclusive environment. When contributing:

  • Be respectful and considerate in all interactions.
  • Provide constructive feedback focused on ideas, not people.
  • Use inclusive language that welcomes diverse perspectives.
  • Assume good intent and communicate with empathy.

If you encounter unacceptable behavior, please open an issue to report it.

Types of contributions welcome

This section describes the various ways you can contribute to improve and expand the framework.

We welcome several types of contributions:

  • Clarity and usability improvements: Make the framework easier to understand and apply.
  • Additional examples: Share anonymized examples from real organizations to illustrate concepts.
  • Translations: Help make the framework accessible in other languages.
  • Bug fixes and typos: Correct errors in documentation or examples.
  • Edge case guidance: Add guidance for unusual situations or constraints.
  • Process adaptations: Suggest adaptations for different organizational contexts (for example, distributed teams, regulated industries, or small startups).
  • Template improvements: Enhance existing templates or propose new ones.

How to contribute

This section explains the workflow for submitting contributions, from small fixes to major changes.

Small changes

For minor fixes like typos, broken links, or small clarifications:

  1. Fork this repository.
  2. Create a branch for your changes.
  3. Make your changes following the style guidelines below.
  4. Submit a pull request with a clear description of what you changed and why.

Significant changes

For substantial changes like new sections, major rewrites, or structural changes:

  1. Open an issue first to discuss your proposed changes.
  2. Wait for feedback from maintainers before investing significant time.
  3. Once the approach is agreed upon, follow the process for small changes above.

This discussion-first approach helps ensure your contribution aligns with the framework's goals and saves everyone time.

Branch naming

While not required, descriptive branch names help reviewers understand your changes:

  • fix/broken-link-in-readme for bug fixes.
  • docs/expand-dependencies-section for documentation improvements.
  • feature/add-compliance-template for new additions.

Commit messages

Write clear commit messages that explain what changed and why:

  • Start with a verb in the present tense: "Add", "Fix", "Update", "Remove".
  • Be specific: "Fix broken link in dependencies section" instead of "Fix link".
  • If fixing an issue, reference it: "Fix broken link in dependencies section (fixes #42)".

Style guidelines

This section defines the writing, formatting, and content standards for all framework documentation.

Follow these guidelines to maintain consistency across the framework:

Writing style

  • Follow the Microsoft Manual of Style for technical content.
  • Use active voice: "Complete the template" instead of "The template should be completed".
  • Write in present tense: "This section describes" instead of "This section will describe".
  • Avoid Latin abbreviations: use "for example" instead of "e.g." and "that is" instead of "i.e.".
  • Keep language tool-agnostic: avoid references to specific software unless necessary.

Formatting

  • Use sentence case for headings: "How to contribute" instead of "How to Contribute".
  • End all list items with periods.
  • Use example-based placeholders: "your product (for example, a feature or service)" instead of generic terms.
  • Use inline code formatting for template field names, file paths, and technical terms: team_name, dependencies, .md, .yaml.

Content

  • Focus on practical guidance over theoretical concepts.
  • Provide concrete examples to illustrate abstract ideas.
  • Keep explanations concise but complete.
  • Consider diverse team contexts when writing guidance.

Testing your changes

This section provides a checklist for validating your contributions before submission.

Before submitting a pull request, verify your changes work correctly:

  1. Check consistency: Read through related documents to ensure your changes align with existing content and don't contradict other sections.
  2. Verify links: Test all internal and external links to confirm they work correctly.
  3. Review examples: Ensure examples are realistic, complete, and anonymized if drawn from real organizations.
  4. Proofread: Check for spelling, grammar, and formatting errors.

If you're adding or modifying templates, complete the template yourself to verify it's practical and clear.

Recognition

This section explains how we acknowledge contributor efforts.

We value all contributions to this framework. Contributors who submit merged pull requests will be acknowledged in the project. If you prefer not to be listed, let us know in your pull request.

Questions

This section explains how to get help with the contribution process.

Open an issue if you have questions about contributing. We're happy to help you get started or clarify any aspect of the contribution process.