Contributing to IT-Journey

Thank you for your interest in contributing to IT-Journey! We welcome contributions from developers, content creators, and learners of all experience levels. The user-facing version of this guide is the contributing page on it-journey.dev.

🚀 First-Time Contributor Fast Track

New here? Make your first contribution in under 5 minutes!

Perfect first contributions that require no setup:

• Fix a typo in a quest or a README
• Clarify a confusing step in a quest
• Add a comment to a code example

# 1. Fork this repo on GitHub (click "Fork" button)

# 2. Clone and create branch (replace YOUR-USERNAME)
git clone https://github.com/YOUR-USERNAME/it-journey.git
cd it-journey
git checkout -b fix/my-first-contribution

# 3. Make your change (example: fix typo in this file)

# 4. Commit and push
git add .
git commit -m "docs: fix typo in CONTRIBUTING.md"
git push origin fix/my-first-contribution

# 5. Create Pull Request on GitHub

Have an idea for a whole new quest? Shape it in the Quest Idea Forge, which files it as an issue for review.

Types of Contributions

• Quests — write a new quest or improve an existing one under pages/_quests/ (see the quest instructions).
• Notes — cheatsheets and reference notes under pages/_notes/.
• Code — the validation, CMS and quest tooling under scripts/ and test/.
• Documentation — the contributor docs indexed in docs/README.md.
• Community — answer questions, review pull requests, report what confused you.

Blog posts now belong to lifehacker.dev, not this repository.

Contribution Workflow

# 1. Fork and clone
git clone https://github.com/YOUR-USERNAME/it-journey.git
cd it-journey

# 2. Create a branch: feature/, fix/, docs/, chore/ or content/
git checkout -b feature/your-feature-name

# 3. Preview your change at http://localhost:4002
make serve                    # host Ruby >= 3.2, after `bundle install`
docker compose up -d jekyll   # or in Docker (cp .env.example .env first)

# 4. Run the gates CI runs
make build-ci
make content-audit            # plus `make quest-audit` when quests changed
make prose-oneline-apply      # one paragraph per line in markdown

# 5. Commit with a conventional message, push, and open a pull request
git commit -m "feat(quest): add docker basics quest"
git push origin feature/your-feature-name

Commit Message Format: <type>(<scope>): <description>

• Types: feat, fix, docs, style, refactor, test, chore
• Scope: Component affected (quest, notes, ci, scripts, etc.)
• Description: Brief summary in present tense

Layout, CSS or JavaScript changes need before/after screenshots in the pull request. The full rules — quest permalinks, the frontmatter contract, generated files you must not edit — are in AGENTS.md.

Documentation

For Human Contributors

• Developer Contributing Guide - Complete contribution workflow
• Development Environment - Setup instructions
• Content Guidelines - Writing standards
• Frontmatter Standards - Metadata requirements
• Documentation index - Every document in the repository, one line each

For AI Agents

• AGENTS.md - The canonical instructions every agent reads first
• Contributing Instructions - How agents assist human contributors
• README Instructions - Documentation standards
• Quest Instructions - Quest creation patterns
• Feature Instructions - Feature development

Reference

• Jekyll Implementation - Jekyll details
• Workflow reference - CI/CD workflows (generated)
• Make targets - Every make command (generated)
• Scripts Guide - Automation tools
• Testing Frameworks - Quality assurance

Code of Conduct

Everyone taking part follows the Code of Conduct: be respectful and inclusive, welcome newcomers, and keep feedback about the work, not the person.

Getting Help

• Check the documentation index first
• Search existing issues
• Ask in GitHub Discussions or in your pull request
• Bug reports and feature requests: open an issue

Recognition

Contributors are recognized through:

• Repository contributors page
• Release notes acknowledgments
• About page (for significant contributions)

License

By contributing, you agree that your contributions will be licensed under the MIT License.