First-Time Contributor Checklist

Welcome! This checklist will guide you through making your first contribution to rad.io.

Before You Start

Read the README.md to understand what rad.io does
Review the Code of Conduct - we're a respectful community
Check out the Community Guidelines to understand how we work

Setting Up Your Environment

1. Fork and Clone

Fork the repository on GitHub (click "Fork" button)

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/rad.io.git
cd rad.io

Add upstream remote:

git remote add upstream https://github.com/alexthemitchell/rad.io.git

2. Install Dependencies

Ensure you have Node.js 18+ installed
Install dependencies:
```
npm install
```
Verify installation:
```
npm run validate
```

3. Explore the Project

Start the development server:
```
npm start
```
Visit https://localhost:8080 and explore the app

Note: HTTPS is required for WebUSB functionality. The development server uses a self-signed certificate; you will need to accept this certificate in your browser to access the site and use WebUSB features.
Open Monitor: https://localhost:8080/monitor (use ?mockSdr=1 for simulated mode)
Run tests to see everything works:
```
npm test
```

Finding Something to Work On

Browse good first issue labels
Check help wanted issues
Look for issues labeled documentation if you prefer starting there
Ask in Discussions if you need guidance

Good First Contributions

Easy wins for first-time contributors:

Fix typos in documentation
Improve code comments
Add examples to guides
Fix simple bugs
Write tests for existing code
Improve error messages

Making Your Changes

1. Create a Branch

Update main branch:

git checkout main
git pull upstream main

Create a feature branch:

git checkout -b feature/your-feature-name

2. Make Your Changes

Follow the code style (linter will help)
Add tests if adding/changing functionality
Update documentation if needed
Keep commits focused and logical

3. Test Your Changes

Run linting:

npm run lint
npm run lint:fix  # Auto-fix issues

Run type checking:
```
npm run type-check
```
Run tests:
```
npm test
```
Test in browser manually
Run full validation:
```
npm run validate
```

4. Commit Your Changes

Stage your changes:
```
git add .
```
Commit with a clear message:
```
git commit -m "feat: add new feature X"
```
Follow Conventional Commits format
- feat: for new features
- fix: for bug fixes
- docs: for documentation
- test: for tests
- refactor: for refactoring
- chore: for maintenance

Submitting Your Pull Request

1. Push to GitHub

Push your branch:

git push origin feature/your-feature-name

2. Create Pull Request

Go to your fork on GitHub
Click "Pull Request" button
Fill out the PR template completely
Link related issues (use "Fixes #123")
Add screenshots if relevant
Mark as draft if still working on it

3. PR Checklist

Before submitting, verify:

4. Add Yourself to Contributors

Edit CONTRIBUTORS.md
Add your name, GitHub link, and contribution
Include this in your PR

During Review

1. Engage with Reviewers

Respond to comments promptly
Ask questions if feedback is unclear
Make requested changes
Mark conversations as resolved when done
Thank reviewers for their time

2. Making Changes

Make additional commits on the same branch

Push updates:

git add .
git commit -m "fix: address review comments"
git push origin feature/your-feature-name

Re-request review if needed

3. Staying Up to Date

If main branch updates while your PR is open:

Fetch upstream changes:

git fetch upstream
git merge upstream/main

Resolve any conflicts
Push updated branch

After Your PR is Merged

1. Celebrate! 🎉

Your contribution is now part of rad.io!
You're listed in CONTRIBUTORS.md
You're part of the community

2. Clean Up

Delete your feature branch:

git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Update your fork:

git checkout main
git pull upstream main
git push origin main

3. What's Next?

Common Issues and Solutions

Tests Failing

Problem: Tests pass locally but fail in CI

Solution: Run full test suite with npm test (not watch mode)
Solution: Check if you're using consistent Node.js version

Linting Errors

Problem: Linting fails

Solution: Run npm run lint:fix to auto-fix most issues
Solution: Check ESLint output for specific issues

Merge Conflicts

Problem: PR has conflicts with main

Solution: Merge latest main into your branch
Solution: Ask for help in PR comments if stuck

Build Failing

Problem: Webpack build fails

Solution: Delete node_modules and dist, run npm install again
Solution: Check Node.js version (need 18+)

Getting Help

Stuck or Confused?

Ask in your PR: Maintainers are happy to help
GitHub Discussions: Great for general questions
Documentation: Check docs/ONBOARDING.md
Issues: Comment on the issue you're working on

Need Guidance?

We're here to help newcomers!
No question is too small
We all started somewhere
Be patient with yourself

Resources

Essential Reading

Contributing Guide - Detailed contribution guidelines
Onboarding Guide - Technical onboarding
Architecture - System design

Learning Resources

Tips for Success

Do's ✅

Start small - Pick an easy first issue
Ask questions - We're here to help
Test thoroughly - Run all checks before submitting
Be patient - Reviews take time
Learn from feedback - Every comment helps you improve
Have fun - Contributing should be enjoyable!

Don'ts ❌

Don't skip tests - They catch bugs early
Don't ignore linting - Code style matters
Don't be afraid to ask - Confusion is normal
Don't give up - First PR is always hardest
Don't work on large features first - Start small
Don't skip documentation - Future you will thank you

Acknowledgments

Thank you for contributing to rad.io! Your efforts help make this project better for everyone.

Every contribution matters, whether it's code, documentation, bug reports, or helping others. Welcome to the community!

Questions? Open a Discussion or ask in your PR!

Last updated: 2025-10-30

FilesExpand file tree

FIRST_TIME_CONTRIBUTOR_CHECKLIST.md

Latest commit

History