Complete Developer Contribution Guide

By IT-Journey Team

Comprehensive instructions for developers and AI agents contributing to the IT-Journey repository

Estimated reading time: 15 minutes

Edit on GitHub

Developer Contribution Guide

This guide provides comprehensive instructions for developers and AI agents contributing to the IT-Journey repository.

Getting Started
Development Workflow
Code Standards
Testing Requirements
Pull Request Process
AI Agent Guidelines

Getting Started

Prerequisites

Before contributing, ensure you have:

Development Environment Set Up
- Follow Development Environment Setup
- Verify local build works: bundle exec jekyll serve --config _config_dev.yml
Familiarity with Project Structure
- Read Repository Structure
- Review Jekyll Implementation
Understanding of Standards
- Review Frontmatter Standards
- Read Content Guidelines

Fork and Clone

# 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

Development Workflow

1. Sync with Upstream

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

2. Create Feature Branch

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

3. Make Changes

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

4. Commit Changes

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

5. Push Changes

# 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

Code Standards

Frontmatter Standards

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
---

See the Frontmatter Standards for complete details.

Markdown Standards

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 the [Content Guidelines](https://github.com/bamr87/it-journey/blob/main/docs/standards/CONTENT_GUIDELINES.md) for complete details.

### Script Standards

Scripts must follow these conventions:

```bash
#!/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 "$@"

Python Standards

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

Creating New Pages

Adding a New Post

Blog posts live in pages/_posts/ and follow a date-based naming convention:

# File naming format: YYYY-MM-DD-descriptive-title.md
touch pages/_posts/YYYY-MM-DD-your-post-title.md

Required frontmatter for posts:

---
title: "Your Post Title"
description: "Brief description"
author: "Your Name"
date: 2025-01-01T00:00:00.000Z
lastmod: 2025-01-01T00:00:00.000Z
categories:
  - your-category
tags:
  - tag1
  - tag2
draft: false
---

Adding a New Quest

Quests live in pages/_quests/ organized by level:

# Level directories use binary naming: lvl_000, lvl_001, lvl_010, etc.
mkdir -p pages/_quests/lvl_001/your-quest-name
touch pages/_quests/lvl_001/your-quest-name/index.md

Required frontmatter for quests:

---
title: "Your Quest Title"
description: "Quest description"
difficulty: beginner  # beginner, intermediate, advanced, expert
categories:
  - quests
  - your-category
tags:
  - tag1
  - tag2
date: 2025-01-01T00:00:00.000Z
lastmod: 2025-01-01T00:00:00.000Z
draft: false
---

Adding a New Doc Page

Doc pages live in pages/_docs/ and provide learning resources:

# Create a directory for a new topic
mkdir -p pages/_docs/your-topic/
touch pages/_docs/your-topic/index.md

Required frontmatter for doc pages:

---
title: "Your Doc Title"
description: "What this doc covers"
permalink: /docs/your-topic/
date: 2025-01-01T00:00:00.000Z
lastmod: 2025-01-01T00:00:00.000Z
categories:
  - your-topic
tags:
  - tag1
sidebar:
  nav: docs
---

After creating doc pages, update _data/navigation/docs.yml to add them to the sidebar navigation.

Testing Requirements

Local Testing Checklist

Before submitting PR, verify:

Run Tests Locally

# 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

Automated Testing

CI/CD runs automatically on PR:

Build validation
Frontmatter validation
Link checking (internal only for PRs)
CodeQL security scanning

Pull Request Process

1. Create Pull Request

# Push your branch
git push origin feature/your-feature

# Go to GitHub and click "Create Pull Request"

2. PR Title and Description

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.

3. Code Review Process

For Contributors:

Respond to review comments promptly
Make requested changes in new commits
Update PR description if scope changes
Resolve conflicts with main branch

For Reviewers:

Review within 48 hours when possible
Be constructive and specific
Suggest improvements, not just problems
Approve when standards are met

4. Merging

Requirements for Merge:

At least one approval from maintainer
All CI checks passing
No merge conflicts
Up to date with main branch
Documentation updated (if needed)

Merge Process:

Maintainer reviews and approves
Squash and merge (default) or merge commit
Delete feature branch
Close related issues

Branch Protection Rules

The main branch is protected with these rules:

Require pull request reviews (1 approval minimum)
Require status checks to pass
- Build validation
- Frontmatter validation
- CodeQL analysis
Require branches to be up to date before merging
Require signed commits (recommended)
Include administrators

AI Agent Guidelines

Context for AI Assistants

When working on this repository, AI agents should:

Read Documentation First
- Start with Repository Structure
- Review relevant standards before making changes
Follow Established Patterns
- Look at existing similar content/code
- Match style and structure
- Use same tools and workflows
Validate Changes
- Test builds locally
- Check frontmatter
- Verify links work
- Run applicable tests
Provide Context
- Explain reasoning in commit messages
- Document decisions in PRs
- Link to relevant documentation

Contributing with GitHub Copilot

GitHub Copilot coding agent lets you delegate GitHub issues directly to an AI agent that operates within the repository’s own CI environment. Here is how to use it for IT-Journey contributions:

1. Assign an Issue to Copilot

Open any open GitHub issue in the it-journey repository.
In the Assignees panel on the right sidebar, click the gear icon and select Copilot.
Copilot will automatically open a pull request on a new branch and begin working on the issue.

Tip: Write clear, detailed issue descriptions. The more context you provide (acceptance criteria, affected files, expected behavior), the better the agent’s output will be.

2. Monitor the Agent’s Work

Watch the pull request created by Copilot. Each time it pushes a commit, GitHub Actions will run the standard CI checks (build validation, frontmatter validation, CodeQL).
The agent posts progress updates as comments on the PR. Review these to understand what it has done and what remains.

3. Review and Collaborate

Read the diff carefully — AI agents can occasionally miss project-specific conventions.
Leave review comments as you would for any human contributor; Copilot can respond to and address feedback.
Check that all CI checks are green before approving.

4. Merge

Once the PR is approved and all checks pass, merge using the standard Squash and merge strategy.
Delete the agent’s branch after merging.

5. Copilot Setup Steps

IT-Journey maintains a copilot-setup-steps.yml workflow that pre-installs Ruby, Bundler, and other dependencies so the agent’s environment matches local development. You do not need to configure anything extra — it is applied automatically when Copilot runs.

Contributing with Other AI Agents

You can also use AI coding assistants (Claude, ChatGPT, Gemini, etc.) locally via your editor to prepare contributions:

Recommended Workflow

# 1. Fork and clone the repository
git clone https://github.com/<your-username>/it-journey.git
cd it-journey

# 2. Create a feature branch
git switch -c feature/my-ai-assisted-contribution

# 3. Install dependencies
bundle install

# 4. Use your AI assistant to draft changes
#    (VS Code + GitHub Copilot, Cursor, Continue.dev, etc.)

# 5. Verify the site builds locally
bundle exec jekyll build --config _config.yml,_config_dev.yml

# 6. Run frontmatter validation
#    (check pages/_docs/ and pages/_posts/ for required fields)

# 7. Commit following Conventional Commits
git add .
git commit -m "feat(docs): add AI agent contribution instructions"

# 8. Push and open a pull request
git push origin feature/my-ai-assisted-contribution

Using AI Assistants Effectively

Task	Prompt strategy
Create a new doc page	“Create a Jekyll Markdown file in `pages/_docs/<topic>/` with the required frontmatter fields: title (≥30 chars), description, excerpt, keywords, author, date, lastmod, categories, tags, sidebar nav, toc_sticky, and permalink.”
Fix frontmatter issues	“Audit this file’s YAML frontmatter against the Frontmatter Standards and add any missing required or recommended fields.”
Improve content quality	“Review this doc for clarity, accuracy, and completeness. Suggest additions that would help a developer contributor understand the workflow.”
Update an existing guide	“Update this file to reflect [change]. Maintain the existing voice and structure. Update the `lastmod` date to today.”
Write a blog post	“Draft a Jekyll post following the template in `.github/instructions/posts.instructions.md`. Include all required frontmatter.”

AI Agent Do’s and Don’ts

✅ Always update lastmod when modifying a file
✅ Run bundle exec jekyll build to verify the site compiles
✅ Provide clear PR descriptions explaining what was changed and why
✅ Follow the README-First, README-Last principle
✅ Respect the Conventional Commits format

❌ Do not commit secrets, API keys, or credentials
❌ Do not modify CI workflow files unless explicitly asked
❌ Do not remove or reorder existing frontmatter fields without understanding the impact
❌ Do not hard-code absolute local paths
❌ Do not bypass branch-protection rules with force pushes

AI-Specific Workflows

For Content Creation:

Review existing content in same collection
Follow frontmatter template exactly
Match writing style and tone
Include all required fields (title ≥30 chars, excerpt, keywords)
Test markdown rendering

For Code Changes:

Review similar existing code
Follow established patterns
Add comprehensive error handling
Include usage examples
Update documentation

For Documentation Updates:

Review entire document for consistency
Update cross-references
Maintain formatting standards
Test all links
Update "Last Updated" date and lastmod frontmatter field

Communication

Getting Help

Questions:

Create discussion in GitHub Discussions
Ask in pull request comments
Create issue with question label

Bug Reports:

Create issue with bug label
Include reproduction steps
Provide system information
Include error messages/logs

Feature Requests:

Create issue with enhancement label
Describe use case and benefits
Suggest implementation approach

Response Times

We strive for:

Issues: Response within 48 hours
Pull Requests: Review within 48 hours
Discussions: Response within 72 hours

Best Practices

Do’s

✅ 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

Don’ts

❌ 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

Recognition

Contributors are recognized in:

Repository contributors page
Release notes
About page (for significant contributions)
Special acknowledgment in related content

License

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

Additional Resources

Documentation

External Resources

Questions or Problems?

Documentation Issues: Open issue or PR with corrections
Process Questions: Create discussion in GitHub Discussions
Technical Problems: Create issue with help wanted label
Security Issues: Email security@it-journey.dev (do not create public issue)

Thank you for contributing to IT-Journey! Your efforts help build a better learning platform for everyone.

Last Updated: 2026-05-06

Version: 2.0.0

Maintained by: IT-Journey Team

Layout	`default`
Collection	`docs`
Path	`_docs/contributing/contributing-developer.md`
URL	`/docs/contributing/contributing-developer/`
Date	`2025-10-13`