Contributing to How to Harden

Thank you for your interest in contributing to How to Harden! This document provides guidelines for contributing new guides, improvements, and fixes.

Ways to Contribute

1. Report Issues or Bugs

2. Improve Existing Guides

3. Create New Guides

Markdown Formatting Requirements

⚠️ CRITICAL: Our website uses Jekyll with kramdown for Markdown rendering. Certain formatting rules MUST be followed or content will not render correctly.

Tables

Tables MUST have blank lines before and after them.

✅ Correct:

**Step 1: Configure Settings**

| Setting | Value |
|---------|-------|
| Option  | Value |

**Step 2: Next Action**

❌ Incorrect (will break on website):

**Step 1: Configure Settings**
| Setting | Value |
|---------|-------|
| Option  | Value |
**Step 2: Next Action**

Other Formatting Guidelines

Versioning

HTH uses Extended SemVer with Maturity Qualifiers, aligned with CIS Benchmarks versioning practices. See VERSIONS.md for full documentation.

Version Format

v{MAJOR}.{MINOR}.{PATCH}-{maturity}

Examples:
  v0.1.0-draft      # Initial AI-drafted guide
  v0.1.1-draft      # Typo fixes (PATCH)
  v0.2.0-draft      # New control added (MINOR)
  v1.0.0-verified   # First verified release (MAJOR milestone)
  v2.0.0-verified   # Net-new product added (MAJOR scope expansion)

When to Increment Versions

Bump Signals Triggers
MAJOR Scope expansion or milestone Net-new product, major feature area, first verified release, structural overhaul
MINOR Incremental improvements New controls, new sections, compliance mappings
PATCH Editorial/maintenance Typos, URL fixes, vendor UI changes, clarifications

Changelog Tags

Use tags to signal special circumstances (version bump follows normal rules):

Tag When to Use Example
[SECURITY] Addresses active/prevalent threat [SECURITY] Add L1: Phishing-resistant MFA
[BREAKING] May disrupt existing implementations [BREAKING] Remove deprecated OAuth control

Maturity Levels

Level Meaning Who Can Set
draft AI-generated or unreviewed Any contributor
reviewed Expert validated Maintainers only
verified Production tested Maintainers only

Author Attribution in Changelog

Properly attribute all contributions:

Author Type Format Example
Human contributor GitHub handle or name @username, Jane Doe
Claude Code Claude Code ({model}) Claude Code (Opus 4.5)
Other AI tools {Tool Name} ({model}) GitHub Copilot (GPT-4)

Required Updates for Version Changes

  1. YAML front matter: Update version field
  2. Changelog table: Add new row with date, version, maturity, changes, author
  3. VERSIONS.md: Update the central registry

Creating a New Guide

1. Choose a Platform

Priority platforms that need guides:

2. Use the Template

cp templates/vendor-guide-template.md docs/_guides/[vendor-name].md

3. Fill Out All Sections

See the template usage notes for detailed guidance.

4. Test Everything

5. Set Version and Maturity

For new guides:

6. Submit a Pull Request

Pull Request Process

  1. Fork the repository and create a branch from main
  2. Make your changes following the guidelines above
  3. Test locally if possible (see Local Development)
  4. Submit a PR with a clear description of changes
  5. Respond to review feedback from maintainers
  6. Celebrate! Your contribution helps the security community

Local Development

To test the Jekyll site locally:

# Install dependencies
cd docs
bundle install

# Run local server
bundle exec jekyll serve

# View at http://localhost:4000

This allows you to verify that your Markdown renders correctly before submitting a PR.

Style Guide

Writing Style

Code Examples

Security Focus

Compliance Mappings

When adding compliance mappings:

  1. Verify against official sources:

  2. Be specific: Map to exact control IDs, not just categories

  3. Explain the relationship: Why does this technical control satisfy the compliance requirement?

Security Reporting

If you discover a security vulnerability in our automation scripts or recommendations that could actively harm users:

For general content corrections or improvements, use GitHub Issues.

Recognition

All contributors are recognized in:

Questions?

License

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

Thank you for helping make the security community stronger!