Skip to main content

Contributing to Fellowship Exercises

We'd love your help! Whether you're adding new exercises, improving documentation, fixing bugs, or sharing ideas, your contributions make this project better for everyone.

Ways to Contribute​

📚 Documentation​

  • Fix typos or unclear explanations
  • Add more examples or diagrams
  • Improve troubleshooting guide
  • Document edge cases
  • Add missing sections

🐛 Bug Reports​

  • Report issues you find
  • Include steps to reproduce
  • Share error messages and logs
  • Suggest fixes if you have ideas

✨ Feature Ideas​

  • Suggest new exercises
  • Propose new tools or MCP servers
  • Ideas for better agent patterns
  • Improvements to architecture

💻 Code Contribution​

  • Add missing implementations
  • Improve existing code
  • Add or fix tests
  • Optimize performance
  • Add new language support

Getting Started​

Fork & Clone​

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/LOTR-tutorial.git
    cd LOTR-tutorial

Create a Branch​

git checkout -b feature/my-awesome-contribution

Use descriptive branch names:

  • fix/typo-in-exercise-1
  • docs/add-troubleshooting-section
  • feature/new-exercise-6

Make Changes​

Write code that:

  • ✅ Is clear and readable
  • ✅ Follows the project's style
  • ✅ Has tests for new functionality
  • ✅ Doesn't break existing tests
  • ✅ Is well-documented

Test Locally​

# Run tests
npm test
pytest

# Build documentation
npm run docs:build

# Check for errors
npm run lint

Commit with Good Messages​

git add .
git commit -m "Add troubleshooting for permission errors

- Document the issue
- Provide solution steps
- Include example commands"

Good commits:

  • Have a clear subject (50 chars)
  • Explain the why, not just the what
  • Can be reverted safely (one thing per commit)

Submit a Pull Request​

  1. Push your branch:

    git push origin feature/my-awesome-contribution

  2. Go to GitHub and create a Pull Request

    • Link related issues
    • Describe your changes
    • Explain why this improvement matters

  3. Review feedback and iterate

Code Standards​

Python​

# ✅ Good
def solve_problem(input_data: str) -> str:
    """Solve the problem.
    
    Args:
        input_data: The problem description
        
    Returns:
        The solution
    """
    result = process(input_data)
    return result

# ❌ Bad
def solve(x):
    # process x here
    y = something(x)
    return y

TypeScript​

// ✅ Good
function solveProblem(inputData: string): string {
  const result = process(inputData);
  return result;
}

// ❌ Bad
function solve(x: any) {
  let y = something(x);
  return y;
}

Documentation​

# ✅ Good Style

## Clear Heading
Brief intro paragraph.

### Concept
Explanation with examples:
\`\`\`python
example_code()
\`\`\`

### Steps
1. First step
2. Second step

### Common Issues
Q: Problem?
**A:** Solution

# ❌ Avoid
- Very long sections without breaks
- Code without explanation
- Assuming reader knowledge
- Typos and grammatical errors

Documentation Style Guide​

Structure​

  • Use clear headings
  • Break into small sections
  • Include examples
  • Add troubleshooting Q&A
  • Provide next steps

Tone​

  • Friendly and encouraging
  • Assume some learner confusion
  • Be specific and actionable
  • Avoid jargon (or explain it)

Examples​

  • Always show complete, runnable code
  • Include expected output
  • Show common variations
  • Explain what each part does

Testing​

Add Tests for New Code​

# Python
def test_my_feature():
    result = my_function("input")
    assert result == "expected"
// TypeScript
test("my feature works", () => {
  const result = myFunction("input");
  expect(result).toBe("expected");
});

Run Tests​

npm test              # All tests
npm test -- --watch  # Watch mode
pytest               # Python tests
pytest -v            # Verbose

Documentation Changes​

For doc-only changes:

  1. Edit the markdown file
  2. Preview locally if possible
  3. Check for typos
  4. Submit PR with title starting with docs:

Example:

docs: add troubleshooting for API key errors

Exercise Contributions​

Want to add a new exercise? Great! Here's the structure:

exercise-N/
├── README.md              # Main exercise guide
├── requirements.txt       # Python dependencies
├── package.json           # Node.js dependencies
├── src/
│   └── starter.py         # Starter template
├── test_solution.py       # Test file
├── solutions/
│   └── solution.py        # Example solution
└── docs/
    └── CONCEPTS.md        # Deep-dive into concepts

Communication​

Getting Help​

  • Comment on issues for discussion
  • Ask in pull request reviews
  • Reach out to maintainers

Code Review​

When your PR is reviewed:

  • ✅ Thank reviewers for feedback
  • ✅ Ask questions if unclear
  • ✅ Push new commits to address feedback
  • ✅ Respond to every comment

Community Norms​

Be Respectful​

  • Welcome diverse perspectives
  • Assume good intent
  • Give constructive feedback
  • Help others learn

Be Clear​

  • Explain your changes
  • Ask questions when confused
  • Provide context in issues
  • Share what you learned

Be Patient​

  • Reviews take time (1-3 days typical)
  • Not all ideas can be accepted
  • It's okay to disagree respectfully
  • Learning > perfection

Recognition​

We appreciate all contributions! Every commit shows our gratitude:

  • Updates to CONTRIBUTORS.md
  • Mention in release notes
  • Credit in exercise docs

Resources​

Questions?​

Issues with contributing? Open an issue with the label question or ask in discussions.

Thank you for making Fellowship Exercises better! 🙏

We're excited to see what you create. Let's build something amazing together. 🚀