Skip to content

docs: add more detailed newcomer guide content to CONTRIBUTING.md #338

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.

Sign up for GitHub

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

Draft
MoralCode wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs: add more detailed newcomer guide content to CONTRIBUTING.md #338

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39baac8
docs: improve newcomer onboarding in CONTRIBUTING.md
iGufrankhan Dec 7, 2025
250fb90
docs: improve onboarding flow and refine issue guidance
iGufrankhan Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 31 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,42 @@ We love to pull requests from everyone! We follow the standard Git workflow of `
If you are new to open source, we recommend GitHub's excellent guide on "[How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)". In addition, please feel free to reach out to any of the maintainers or other community members if you are struggling as we are here to help you learn!

Before getting started, please make sure you've read the [README](README.md) to get a primer on our project. Augur's documentation can be found [here](https://oss-augur.readthedocs.io/en/main/).

## Join the Community

We encourage all contributors to join the [CHAOSS Slack workspace](https://chaoss.community/kb-getting-started/) and participate in the `#wg-augur-8knot` channel. This is a great place to ask questions, get help with issues, participate in discussions, and stay updated on community meetings and planning. Don't hesitate to introduce yourself and ask for help if you get stuck!

## Your Journey from Newcomer to Confident Contributor
New to open source or Augur? Here's how most people get started. Go at your own pace.
### 1. Join the Community & Learn How Things Work
- **Join Slack**: Go to the [CHAOSS Community getting started guide](https://chaoss.community/kb-getting-started/) to join the community Slack workspace and introduce yourself in `#wg-augur-8knot`.
- **Read CHAOSS Docs**: Look at the [Code of Conduct](https://chaoss.community/code-of-conduct/) and browse the [CHAOSS website](https://chaoss.community/)
- **Review this CONTRIBUTING.md**: Get familiar with our contribution guidelines and current project policies
- **Attend Meetings**: Check the [CHAOSS calendar](https://chaoss.community/chaoss-calendar/) for meetings like:
- Newcomer Hangout
- Community Call
- Augur/8-Knot Software Working Group
- **Watch Recordings**: Find past meetings on the [CHAOSS YouTube channel](https://www.youtube.com/@CHAOSStube)
- **Request a Tour Guide** (Optional): Not sure where to start? Ask in the `#newcomers` Slack channel for 1:1 help
### 2. Run Augur
- **Read the Docs**: Start at [Augur documentation](https://oss-augur.readthedocs.io/en/main/) (check out the Docker setup guide)
- **Install Augur**: Follow the installation instructions [getting-started-guide](https://oss-augur.readthedocs.io/en/main/getting-started/toc.html) to get it running on your machine
- **Getting Started Video**: Set up and run Augur on [YouTube](https://www.youtube.com/watch?v=SXLnWwwSsSE)
### 3. Start with Good First Issues
1. Go to the [issues page](https://github.com/chaoss/augur/issues).
2. Use the **Labels** filter to narrow down issues:
- [`good first issue`](https://github.com/chaoss/augur/labels/good%20first%20issue) — recommended for new contributors.
- [`first-timers-only`](https://github.com/chaoss/augur/issues?q=state%3Aopen+label%3Afirst-timers-only) — specifically for first-time contributions.
3. Choose an issue that looks manageable and interesting.
4. If you find a bug or something unclear, open an issue or ask for guidance before starting work.
### 4. Need Help?
- Ask questions in the Slack workspace linked above.
- Bring questions to community meetings.
- Comment on the issue or PR you're working on.
### 5. Ready for More?
- Try [`challenging first issue`](https://github.com/chaoss/augur/labels/challenging%20first%20issue) labels
- Look at [`documentation`](https://github.com/chaoss/augur/labels/documentation) or [`tech debt`](https://github.com/chaoss/augur/labels/tech%20debt) issues
- Ask in the Slack workspace linked above what would be a good fit for your interests.
## Opening an issue
If you're experiencing an issue with Augur or have a question you'd like help answering, please feel free to open an [issue](https://github.com/chaoss/augur/issues). To help us prevent duplicates, we kindly ask that you briefly search for your problem or question in our [issues](https://github.com/chaoss/augur/issues) before opening a new one.

Please note that if you open a bug report and your issue **does not** follow our template, we cannot help you until you have provided us all the relevant information in that format.
Respectfully, we do not have the time to try and recreate an error given with minimal or no context, so by providing this information you are helping us help you!

### How to submit a bug report
To see the template referred to in the above section, click on **New Issue**, then click on the **Get Started** button on the **Bug Report** option.
A dialogue box populated with descriptions of what to put in each section, will pop up on a new page.
Expand Down