Making Your First Contribution¶
This guide walks you through making your first contribution to Arctyk ITSM.
Before You Start¶
Make sure you have:
- Set up your development environment
- Read the team structure
- Reviewed the coding standards
- Familiarized yourself with the architecture
Step 1: Find Something to Work On¶
Good First Issues¶
The easiest way to start is by tackling issues labeled good first issue on GitHub:
- Browse Good First Issues
- Read through the issue description
- Comment that you'd like to work on it
- Wait for confirmation from a maintainer
Other Contribution Ideas¶
- Documentation: Fix typos, improve clarity, add examples
- Tests: Increase test coverage for existing features
- Bug Fixes: Reproduce and fix reported bugs
- Small Features: Implement minor enhancements
Tip
Start small! Your first PR should be focused and easy to review.
Step 2: Create a Branch¶
Always create a new branch for your work:
# Make sure you're on main and up-to-date
git checkout main
git pull origin main
# Create a new branch with a descriptive name
git checkout -b fix/issue-123-ticket-creation-bug
# Branch naming conventions:
# - fix/issue-number-description (for bug fixes)
# - feature/issue-number-description (for new features)
# - docs/description (for documentation)
# - refactor/description (for code refactoring)
Step 3: Make Your Changes¶
Code Changes¶
Follow these guidelines:
- Keep it focused - One logical change per PR
- Follow standards - Use Black for formatting, Pylint for linting
- Write tests - Add tests for new functionality
- Update docs - Document new features or changes
Documentation Changes¶
If updating docs:
- Edit markdown files in the
docs/directory - Preview changes locally:
mkdocs serve - Check for broken links
- Ensure formatting is consistent
Step 4: Commit Your Changes¶
Write clear, descriptive commit messages following our conventions:
# Stage your changes
git add .
# Commit with a descriptive message
git commit -m "fix: resolve ticket creation validation error
- Add validation for required fields
- Display error messages in UI
- Add unit tests for form validation
Fixes #123"
Commit Message Format¶
Types: - feat: - New feature - fix: - Bug fix - docs: - Documentation changes - style: - Code style changes (formatting, etc.) - refactor: - Code refactoring - test: - Adding or updating tests - chore: - Maintenance tasks
See the commit conventions for more details.
Step 5: Push Your Branch¶
Step 6: Open a Pull Request¶
- Go to the Arctyk ITSM repository
- Click "Pull requests" → "New pull request"
- Select your branch
- Fill out the PR template:
## Description
Brief description of changes
## Related Issue
Fixes #123
## Changes Made
- List of specific changes
- Another change
## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] No new warnings
## Screenshots (if applicable)
[Add screenshots for UI changes]
## Checklist
- [ ] Code follows project style guidelines
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Commit messages follow conventions
Step 7: Respond to Review Feedback¶
What to Expect¶
- Maintainers will review your PR within 48 hours
- They may request changes or ask questions
- Don't take feedback personally - it's about the code, not you!
- Reviews are learning opportunities
Making Requested Changes¶
# Make the requested changes
# ... edit files ...
# Commit the changes
git add .
git commit -m "fix: address review feedback
- Update validation logic
- Add missing test case"
# Push to the same branch
git push origin fix/issue-123-ticket-creation-bug
The PR will automatically update with your new commits.
Step 8: Merge and Celebrate! 🎉¶
Once approved:
- A maintainer will merge your PR
- Your changes will be part of the next release
- You'll be listed as a contributor!
After Merge¶
# Switch back to main
git checkout main
# Pull the latest changes (including your contribution!)
git pull origin main
# Delete your local branch
git branch -d fix/issue-123-ticket-creation-bug
Common First Contribution Mistakes¶
Too Large¶
❌ Problem: PR changes 30 files and adds a major feature
✅ Solution: Break it into smaller, focused PRs
Missing Tests¶
❌ Problem: New code has no tests
✅ Solution: Add unit tests for your changes
Not Following Standards¶
❌ Problem: Code doesn't pass linting
✅ Solution: Run Black and Pylint before committing
Unclear Description¶
❌ Problem: PR says "fixed stuff"
✅ Solution: Write clear description of what and why
Tips for Success¶
Communication¶
- Ask questions early if you're unsure
- Keep maintainers updated on progress
- Be responsive to feedback
Code Quality¶
- Run tests before pushing
- Follow existing code patterns
- Keep it simple and readable
Documentation¶
- Update relevant docs with your changes
- Add code comments for complex logic
- Include examples where helpful
Example First Contributions¶
Documentation Fix¶
git checkout -b docs/fix-installation-typo
# Edit docs/getting-started/installation.md
git commit -m "docs: fix typo in installation guide"
git push origin docs/fix-installation-typo
Simple Bug Fix¶
git checkout -b fix/issue-42-date-format
# Edit src/tickets/views.py
# Add test in src/tickets/tests/test_views.py
git commit -m "fix: correct date format in ticket list
Fixes #42"
git push origin fix/issue-42-date-format
Add Missing Test¶
git checkout -b test/ticket-validation
# Add test in src/tickets/tests/test_forms.py
git commit -m "test: add validation tests for TicketForm"
git push origin test/ticket-validation
Getting Help¶
Stuck? Here's where to get help:
- Discord: Ask in the #development channel
- GitHub Discussions: Start a discussion
- PR Comments: Ask questions directly in your PR
- Documentation: Check the developer guide
Next Steps¶
After your first contribution:
- Look for more issues to tackle
- Help review others' PRs
- Improve documentation in areas you've learned
- Share your experience with new contributors
Welcome to the team! 🚀