Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (50 loc) · 4.53 KB

CONTRIBUTING.md

File metadata and controls

80 lines (50 loc) · 4.53 KB
Raw

IN PROGRESS - not yet approved

Contributing to the WORK GROUP NAME

First off, thank you for considering contributing to our work group! It's people like you that make open-source communities thrive.

Our workgroup focuses on delivering high-quality, accessible, and accurate guides for our community. Whether you want to write a completely new guide, fix a typo in an existing one, or review someone else's draft, your help is incredibly valuable.

This document outlines the process for contributing to our repository to keep things organized, collaborative, and efficient for everyone.

🤝 Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. We expect all contributors to be respectful, constructive, and welcoming to others.

📝 How You Can Contribute

We welcome contributions of all sizes. Here are the primary ways you can get involved:

  • Proposing a New Guide: Have an idea for a guide that doesn't exist yet? Open an issue using the "Guide Proposal" template. Outline the target audience, the core problem it solves, and a brief outline.
  • Drafting a Guide: Claim an open issue that is marked as help wanted or needs drafting.
  • Reviewing Guides: Great guides require great editors. Reviewing open Pull Requests (PRs) for clarity, technical accuracy, and grammar is one of the most impactful ways to help.
  • Fixing Typos and Maintenance: Technology changes quickly. If you spot outdated information, broken links, or typos in our existing guides, please submit a PR to fix them!

🔄 The Contribution Workflow

We follow a standard GitHub flow. If you are ready to contribute, please follow these steps:

1. Find or Create an Issue

Before you start writing, check our Issue Tracker.

  • If you're fixing a small typo, you can skip creating an issue and go straight to a Pull Request.
  • For new guides or major rewrites, please open an issue first to discuss it with the maintainers. This ensures you don't waste time working on something that might not align with the group's current goals.

2. Fork and Branch

  1. Fork the repository to your own GitHub account.
  2. Clone the project to your local machine.
  3. Create a branch for your work. Use a descriptive naming convention:
    • feat/guide-name (for new guides)
    • fix/guide-name-typo (for fixes)
    • update/guide-name (for updating outdated guides)

3. Write and Format

Draft your guide in your local branch. We use Markdown for all of our guides.

Tip: If you are adding media, place all images in the assets/images/ directory and compress them to ensure fast loading times.

4. Submit a Pull Request

Once your work is ready for review:

  1. Push your branch to your forked repository.
  2. Open a Pull Request (PR) against our main branch.
  3. Fill out the PR template provided, linking back to the original issue (e.g., "Resolves #123").

📖 Style and Quality Standards

To ensure our guides remain consistent and high-quality, please keep the following guidelines in mind while writing:

Standard Description
Tone Keep it professional, empathetic, and encouraging. Avoid assumptions of prior knowledge like "simply" or "obviously."
Clarity Use active voice and short, easily digestible sentences. Break up large walls of text with headers and bullet points.
Formatting Follow standard Markdown formatting. Use bold text for UI elements (e.g., Click Save) and backticks for code inline (e.g., npm install).
Accessibility Include descriptive alt text for all images and diagrams.

👀 The Review Process

Once you submit a PR, a maintainer will review your work.

  • Feedback: Expect constructive feedback. It is very rare for a PR to be merged on the first try without any requested tweaks. Don't take it personally; editing is a collaborative process!
  • Approvals: A PR requires at least one approval from a designated workgroup maintainer before it can be merged.
  • Stale PRs: If a PR requires changes and sees no activity for 30 days, we may close it to keep our queue clean. You can always request to reopen it when you're ready to continue.

💬 Getting Help

If you're stuck, need help formatting your Markdown, or aren't sure how to use Git, don't hesitate to reach out! You can ask questions directly in the GitHub Issue you are working on, or join and upcoming meeting or join the various discussion channels ( details here ).

Thank you for helping us build better guides!