Skip to content

CONTRIBUTING-template.md

Latest commit

 

History

History
246 lines (148 loc) · 10.1 KB

CONTRIBUTING-template.md

File metadata and controls

246 lines (148 loc) · 10.1 KB
Raw

CONTRIBUTING

** [TODO: rename this file to CONTRIBUTING.md; i.e. remove the template reference]

This is a template document for UC projects can use to help build the documentation in your project repos. It requires editing before it is ready to use, and you can find guides for using these templates on our website. Please feel free to reach out to our Laura, our Community Manager, if you have any questions!

Search for the word TODO in this template to identify parts that require customization; e.g. line 3 above lets you know you should rename this file.. When you finish editing the template, remove the TODO bits.

[TODO: delete the lines between line 1 and the "Welcome" heading]

Welcome!

[TODO: edit welcome text below]

Welcome! We're glad you want to contribute to our project! 💖

As you get started, you're in the best position to give us feedback on areas of our project that we need help with including:

  • Problems found during setting up a new developer environment
  • Gaps in our Quickstart Guide or documentation
  • Bugs in our automation scripts

If anything doesn't make sense, or doesn't work when you run it, please open a bug report and let us know!

Table of Contents

[TODO: edit the Table of Contents]

Ways to Contribute

[TODO: edit this to reflect the kinds of contributions you'd like to receive for your project]

We welcome many different types of contributions, including:

  • New features
  • Builds, CI/CD
  • Bug fixes
  • Documentation
  • Issue Triage
  • Answering questions on Slack/Mailing List
  • Web design
  • Communications/Social Media/Blog Posts
  • Release management

Not everything happens through a GitHub pull request. Please come to [our meetings](TODO: link to your meetings) or [contact us](TODO: link to your preferred method of contact) and let's discuss how we can work together.

Come to Community Calls

[TODO: Maybe your project doesn't have community calls, in which case you can omit this section. But you might consider trying them out!]

Anyone interested in our project is welcome to come to any of [our community calls](TODO: add a link to your community calls)! You never need an invite to join us. In fact, we want you to join us, even if you don’t have anything you feel like you want to contribute. Just being there is enough!

You don’t have to turn on your video. The first time you come, just introducing yourself is perfectly fine. Over time, we hope that you feel comfortable voicing your opinions, giving feedback on others’ ideas, and even sharing your own ideas, and experiences.

Finding an Issue

[TODO: edit this section as needed]

We have good first issues for new contributors and help wanted issues suitable for any contributor. [good first issue](TODO: link your project's good first issue label) has extra information to help you make your first contribution. [help wanted](TODO: link to your project's help wanted label) are issues suitable for someone who isn't a core maintainer and is good to move onto after your first pull request.

Sometimes there won’t be any issues with these labels. That’s ok! There is likely still something for you to work on. If you want to contribute but you don’t know where to start or can't find a suitable issue, you can [TODO: explain how people can ask for an issue to work on].

Once you see an issue that you'd like to work on, please post a comment saying that you want to work on it. Something like "I want to work on this" is fine.

Setting up a Dev Environment

[TODO: edit the steps provided for what's needed for your project]

Clone the project:

git clone yourprojecturl

Install dependencies:

install command

Running Tests

[TODO: Describe the process you use to test code in your project]

  1. Step one
  2. Step two

Asking for Help

The best way to reach us with a question when contributing is to ask on:

[TODO: Pick the way(s) that you prefer people ask for help]

  • The original Github issue
  • The developer mailing list
  • Our Slack channel

Norms for Commits

[TODO: edit this section to reflect what's needed for your project]

Our project uses Conventional Commits, and we require commit signing. Please let us know if you need help with these!

Pull Request Lifecycle

Tip

TODO: Edit the text below to describe your pull request process. You don't need to adopt every aspect! Pick and choose what makes sense for your project]

Before You Submit

[TODO: edit this section to reflect what's needed for your project]

When you submit your pull request, or you push new commits to it, our automated systems will run some checks on your new code. We require that your pull request passes these checks, but we also have more criteria than just that before we can accept and merge it. We recommend that you check the following things locally before you submit your code:

  • First thing to check
  • Another thing to check

When to Submit

[TODO: edit this section to reflect what's needed for your project]

Submit your pull request when you have a working implementation that addresses the issue or feature request. Your code should be tested and ready for review, even if you're open to suggestions for improvements.

Draft vs. Ready PRs

[TODO: edit this section to reflect what's needed for your project]

  • Use Draft PRs when your work is incomplete or you want early feedback on your approach
  • Convert to Ready for Review when your implementation is complete and tested
  • Mark as ready even if you expect minor changes during review

Branch Strategy

[TODO: edit this section to reflect what's needed for your project]

Create a feature branch from the latest main branch. Use descriptive branch names like feature/add-user-authentication or fix/memory-leak-in-parser.

Submission Process

PR Scope

[TODO: edit this section to reflect what's needed for your project]

We prefer small, focused pull requests that address a single issue or implement one feature. Large PRs are harder to review and more likely to conflict with other changes. If your feature is large, consider breaking it into multiple PRs.

Signaling Readiness

[TODO: edit this section to reflect what's needed for your project]

  • Remove "Draft" status when ready for review
  • Ensure all CI checks are passing
  • Include a clear description of what the PR does and why
  • Link to relevant issues using "Fixes #123" or "Addresses #456"

Review Process

[TODO: edit this section to reflect what's needed for your project]

Initial Review Timeline: Expect an initial review within 3-5 business days. Complex PRs may take longer.

Follow-up Reviews: After addressing feedback, expect follow-up reviews within 2-3 business days.

Requesting Reviews

[TODO: edit this section to reflect what's needed for your project]

  • After pushing changes, add a comment like "Ready for re-review" or "@mention" specific reviewers
  • If your PR hasn't been reviewed after the expected timeline, feel free to politely bump with a comment
  • For urgent fixes, mention the urgency in your comment

Handling Common Situations

Stalled Pull Requests

[TODO: edit this section to reflect what's needed for your project]

If your PR appears stalled:

  1. First, check if all feedback has been addressed
  2. After 1 week of no activity, add a polite comment requesting status
  3. If still no response after another week, reach out via [preferred communication channel]

Abandoned Pull Requests

[TODO: edit this section to reflect what's needed for your project]

If you can no longer continue work on your PR:

  • Comment on the PR explaining the situation
  • Maintainers may either:
    • Take over the PR and push additional commits to complete it
    • Close the PR and create a new issue for others to pick up
    • Close the PR if the change is no longer needed

Follow-up Work

[TODO: edit this section to reflect what's needed for your project]

  • Small follow-up changes should be addressed in the same PR when possible
  • Larger follow-ups or new issues discovered during review should be handled in separate issues/PRs
  • Use "TODO" comments sparingly and create follow-up issues for any deferred work

After Your PR is Merged

[TODO: edit this section to reflect what's needed for your project]

Release Timeline: Merged pull requests are included in the next release, which typically happens:

  • Patch releases: Every 2-4 weeks for bug fixes
  • Minor releases: Every 1-3 months for new features
  • Major releases: As needed for breaking changes

Release Process

[TODO: edit this section to reflect what's needed for your project]

After merge, your changes will:

  1. Be available immediately in the main branch
  2. Go through additional testing in our staging environment
  3. Be included in the next scheduled release
  4. Be documented in the changelog with attribution

Staying Updated

[TODO: edit this section to reflect what's needed for your project]

Watch the repository to be notified when your contributions are released. We'll also tag you in release notes when your PR introduces significant changes.

Questions about the PR process? Feel free to ask in the issue comments, discussions, or reach out to the maintainers directly.

Code of Conduct

Please read our [Code of Conduct](TODO: link to your project's CoC)