This guide provides comprehensive instructions for developers and AI agents contributing to the IT-Journey repository.
Before contributing, ensure you have:
bundle exec jekyll serve --config _config_dev.yml# Fork the repository on GitHub (click Fork button)
# Clone your fork
git clone https://github.com/YOUR-USERNAME/it-journey.git
cd it-journey
# Add upstream remote
git remote add upstream https://github.com/bamr87/it-journey.git
# Verify remotes
git remote -v
Before starting work, sync with the main repository:
# Fetch latest changes
git fetch upstream
# Checkout main branch
git checkout main
# Merge upstream changes
git merge upstream/main
# Push to your fork
git push origin main
Use descriptive branch names:
# Branch naming convention
# Type:
# - feature/ (new functionality)
# - fix/ (bug fix)
# - docs/ (documentation)
# - refactor/ (code refactoring)
# - test/ (testing improvements)
# Examples
git checkout -b feature/add-quest-validator
git checkout -b fix/broken-link-in-docs
git checkout -b docs/update-setup-guide
git checkout -b refactor/consolidate-scripts
Code Changes:
# Edit files
# Follow coding standards (see below)
# Test locally
bundle exec jekyll serve --config _config_dev.yml
# Verify in browser
open http://localhost:4002
Content Changes:
# Create or edit markdown files in pages/
# Validate frontmatter
python3 scripts/validate-frontmatter.py pages/_posts/your-post.md
# Test build
bundle exec jekyll build --config _config_dev.yml
Script Changes:
# Make executable
chmod +x scripts/category/new-script.sh
# Test with dry run
./scripts/category/new-script.sh --dry-run
# Check syntax
shellcheck scripts/category/new-script.sh
Follow conventional commit message format:
# Commit message format
<type>(<scope>): <subject>
<body>
<footer>
# Types: feat, fix, docs, style, refactor, test, chore
# Scope: area of change (quest, docs, scripts, workflow, etc.)
# Examples
git commit -m "feat(quest): add automated link checking quest"
git commit -m "fix(docs): correct broken links in setup guide"
git commit -m "docs(architecture): update repository structure"
git commit -m "refactor(scripts): consolidate build scripts"
git commit -m "test(links): improve link checker coverage"
Good Commit Messages:
✅ feat(quest): add link guardian quest with AI analysis
✅ fix(workflow): resolve link checker timeout issues
✅ docs(setup): add Docker setup instructions
✅ refactor(scripts): unify version management scripts
Avoid:
❌ Update files
❌ Fix bug
❌ Changes
❌ WIP
# Push to your fork
git push origin feature/your-feature-name
# If branch already pushed, force push if needed (after rebase)
git push origin feature/your-feature-name --force-with-lease
All content must include proper frontmatter:
---
title: "Descriptive Title"
description: "Brief description for SEO"
author: "Your Name"
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
categories:
- category-one
- category-two
tags:
- tag-one
- tag-two
draft: false
---
Follow markdown best practices:
# Use ATX-style headings with space after #
Use blank lines to separate paragraphs.
- Use `-` for unordered lists
- Keep list items consistent
- Indent nested items properly
1. Use `1.` for all ordered list items
1. Markdown will auto-number
1. Makes reordering easier
Use **bold** for emphasis and *italic* for subtle emphasis.
\`Inline code\` for commands, file names, and code snippets.
\`\`\`language
# Code blocks with language specified
command --option value
\`\`\`
See: Content Guidelines
Scripts must follow these conventions:
#!/usr/bin/env bash
#
# @file scripts/category/script-name.sh
# @description Brief description
# @author IT-Journey Team
# @created 2025-10-13
# @version 1.0.0
# Exit on error
set -e
set -u
set -o pipefail
# Error handling
error_exit() {
echo "Error: $1" >&2
exit 1
}
# Main function
main() {
# Script logic here
echo "Script running..."
}
# Run main
main "$@"
See: Scripts Guide
Python scripts follow PEP 8:
"""
Module description.
@file scripts/category/script-name.py
@author IT-Journey Team
@created 2025-10-13
@version 1.0.0
"""
import sys
from typing import List, Dict
def function_name(param: str) -> bool:
"""
Function description.
Args:
param: Parameter description
Returns:
Return value description
"""
# Implementation
return True
if __name__ == "__main__":
# Main execution
pass
Before submitting PR, verify:
# 1. Test Jekyll build
bundle exec jekyll build --config _config_dev.yml
# 2. Check for issues
bundle exec jekyll doctor
# 3. Validate frontmatter
# (Run on changed files only)
python3 scripts/validate-frontmatter.py pages/_posts/your-post.md
# 4. Check links
python3 scripts/link-checker.py --scope internal
# 5. Test scripts
# If you modified scripts
./scripts/your-script.sh --dry-run
# 6. Check shell scripts
shellcheck scripts/**/*.sh
CI/CD runs automatically on PR:
# Push your branch
git push origin feature/your-feature
# Go to GitHub and click "Create Pull Request"
Title Format:
<type>(<scope>): <description>
Examples:
feat(quest): add link guardian automation quest
fix(docs): correct setup instructions for macOS
docs(contributing): update PR guidelines
Description Template:
## Description
Brief description of changes.
## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
## Checklist
- [ ] Local build succeeds
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] Follows code standards
- [ ] Commits follow convention
## Related Issues
Closes #123
Related to #456
## Screenshots (if applicable)
[Add screenshots here]
## Additional Notes
Any additional context or notes.
For Contributors:
For Reviewers:
Requirements for Merge:
Merge Process:
The main branch is protected with these rules:
When working on this repository, AI agents should:
For Content Creation:
1. Review existing content in same collection
2. Follow frontmatter template exactly
3. Match writing style and tone
4. Include all required fields
5. Test markdown rendering
For Code Changes:
1. Review similar existing code
2. Follow established patterns
3. Add comprehensive error handling
4. Include usage examples
5. Update documentation
For Documentation Updates:
1. Review entire document for consistency
2. Update cross-references
3. Maintain formatting standards
4. Test all links
5. Update "Last Updated" date
Questions:
question labelBug Reports:
bug labelFeature Requests:
enhancement labelWe strive for:
✅ Write clear, descriptive commit messages
✅ Test thoroughly before submitting PR
✅ Update documentation with code changes
✅ Respond promptly to review feedback
✅ Keep PRs focused and reasonably sized
✅ Follow established conventions
✅ Ask for clarification when unsure
❌ Commit directly to main branch
❌ Submit PRs without testing
❌ Ignore CI failures
❌ Make unrelated changes in same PR
❌ Skip documentation updates
❌ Use force push on shared branches
❌ Include sensitive data or secrets
Contributors are recognized in:
By contributing, you agree that your contributions will be licensed under the MIT License, the same license as the project.
help wanted labelThank you for contributing to IT-Journey! Your efforts help build a better learning platform for everyone.
Last Updated: 2025-10-13
Version: 1.0.0