Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Contributing guide to repos #31

Open
maryliag opened this issue Jan 27, 2025 · 1 comment
Open

Add Contributing guide to repos #31

maryliag opened this issue Jan 27, 2025 · 1 comment
Assignees

Comments

@maryliag
Copy link

Add Contributing guide to repos, following the template below:

Introduction (Welcome message to Contributors)

  • A warm, inviting message to make contributors feel welcome.
  • Brief overview of the repository’s purpose and how it fits within the larger project (e.g., OpenTelemetry ecosystem).
  • A statement of appreciation for contributions, regardless of size or scope.
  • Encouragement to ask questions and seek help in the community.

Pre-requisites

  • List of tools, languages, and software required to work with the repository (e.g., programming languages, specific frameworks).
  • Any version requirements or compatibility notes (e.g., "PHP 8.1 or higher").
  • Mention additional platform-specific notes (e.g., macOS, Windows, Linux differences).

Workflow

  • Any specific workflows unique to the repository, such as using specific tools (e.g., Makefile, GitHub Actions).
  • Explanation of PR title conventions
  • Explanation of branch naming conventions and commit message formatting (if there is any).

Local Run/Build

  • How to set up and run the project locally.
  • Commands for building the project and starting the application.
  • Any important files that need to be created or modified (e.g., copying .env.dist to .env).
  • Notes about expected outputs or verification steps to confirm the setup is successful.

Testing

  • How to run the test suite for the repository.
  • Explanation of different types of tests (e.g., unit, integration, or functional).
  • Tools and frameworks used for testing (e.g., PHPUnit, Jest, or pytest).
  • How to interpret test results and resolve common test failures.
  • Mention code coverage expectations or reporting tools if applicable.

Contributing Rules

  • Adhering to coding standards.
  • Writing meaningful commit messages.
  • Including tests for new features or bug fixes.
  • Reference any community standards or style guides.
  • Instructions for signing a Contributor License Agreement (CLA), if required.
  • Links to tags like good first issue or help wanted.

Further Help

  • Details on where contributors can seek assistance:
  • Links to Slack, Discord, or other communication platforms.
  • GitHub Discussions or forums.
  • Documentation references or FAQs.
  • Contact information for maintainers or SIG members.

Troubleshooting Guide

  • Common errors during setup, build, or tests and their resolutions.
  • Platform-specific issues (e.g., Docker daemon errors on Windows).
  • Example error messages with potential fixes.
  • Tips for debugging or where to find logs (e.g., Docker logs, build logs).

Additional Information (Repo-Specific Info)
Any unique details specific to the repository, such as:
Details about automation processes (e.g., CI/CD pipelines).
Notes on optional tasks, like generating documentation or metrics.

Suggestions to Enhance the Guide

  • Add visuals or screenshots where possible (e.g., examples of successful build/test outputs).
  • Provide links to examples of PRs that follow best practices.
  • Highlight beginner-friendly tasks to lower the barrier to entry.
  • Create a quick-start section for contributors who want to dive in with minimal setup.
@RichardChukwu
Copy link

RichardChukwu commented Jan 28, 2025

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: In Progress
Development

No branches or pull requests

2 participants