FixIt/CONTRIBUTING.md

CONTRIBUTING

Make sure that you follow CODE_OF_CONDUCT.md while contributing and engaging in the discussions.

Prerequisites

Before you start contributing, make sure you have the following tools installed:

• Node.js (>= 20.0.0) - Required for package management and build tools
• Hugo Extended (>= 0.158.0) - The static site generator
• pnpm - Package manager (recommended)

You can check your installed versions:

node --version
hugo version
pnpm --version

How to contribute to this project

First, fork this repository by clicking the fork button.

Next, clone your forked repo.

git clone https://github.com/hugo-fixit/FixIt.git && cd FixIt

Then, install the dev dependencies.

pnpm install

And now you are ready to go!

Here are some useful commands for development:

Development

# Start demo site development server
pnpm dev:demo
# Start test site development server
pnpm dev:test
# Start documentation development server (requires fixit-docs as sibling directory)
pnpm dev:docs

Tip

• Add -e production to the development command to check the production environment, e.g. pnpm dev:test -e production.
• Add -e debug to enable debug mode (if applicable), e.g. pnpm dev:test -e debug.
• For documentation-related theme changes, it is recommended to clone both FixIt and fixit-docs as sibling directories.

Building

# Build demo site
pnpm build:demo
# Build test site
pnpm build:test
# Build all sites
pnpm build

Preview

# Preview the built site locally (requires build first)
pnpm preview

Project Structure

Understanding the project structure will help you contribute more effectively:

FixIt/
├── apps/               # Minimal sites
│   ├── demo/           # Demo site
│   └── test/           # Test site
├── archetypes/         # Content templates
├── assets/             # Theme assets
│   ├── scss/           # SCSS stylesheets
│   ├── js/             # JavaScript files
│   ├── images/         # Image assets
│   └── lib/            # Third-party libraries
├── i18n/               # Internationalization files
├── layouts/            # Hugo template files
│   ├── _markup/        # Hugo render hooks
│   ├── _partials/      # Reusable template components
│   └── _shortcodes/    # Custom shortcodes
├── packages/           # Theme-related packages
├── static/             # Static files
├── hugo.toml           # Default theme configuration
└── package.json        # npm scripts and dependencies

Development Workflow

1. Make your changes in the appropriate directories
2. Test locally using pnpm dev or pnpm test
3. Check different environments with production builds
4. Verify documentation changes with pnpm dev:docs (if applicable)
5. Commit your changes following the commit message format below

Pull Request Guidelines

• Create a feature branch from main
• Make your changes with clear, focused commits
• Test your changes thoroughly
• Update documentation if needed
• Submit a pull request with a clear description

Finally, create a new pull request at https://github.com/hugo-fixit/FixIt/pulls to submit your contribution 🎉

Git Commit Guidelines

We follow the Conventional Commits specification for commit messages. This enables automatic changelog generation using our custom template: conventional.hbs.

Note

Commits in a PR will normally be squashed into one commit, so you don't need to rebase locally.

Commit Message Format

<type>(<scope>): <subject>
^      ^         ^
|      |         |__ Subject: Concise description of the change (imperative mood, lowercase).
|      |____________ Scope: The specific part of the codebase affected (optional but recommended).
|___________________ Type: Indicates the kind of change.

Allowed Types

• feat: A new feature.
• fix: A bug fix.
• refactor: Code changes that neither fix a bug nor add a feature.
• chore: Changes to the build process, auxiliary tools, libraries, documentation generation etc.
• docs: Documentation only changes.
• Other conventional types like perf, style, test, ci, build are also acceptable.

Allowed Scopes

• workflow: CI/CD workflow changes (.github/workflows/)
• archetypes: Content templates (archetypes/)
• assets: Changes to theme assets like CSS, JS (assets/)
• i18n: Internationalization and translation files (i18n/)
• layouts: Root-level Hugo template files (layouts/*.html)
• config: Theme configuration (hugo.toml, theme.toml)
• (All top-level directories in the layouts and packages directories)
• (Consider adding other scopes as needed for better granularity)

Examples

• feat(_shortcodes): add mapbox zoom control options
• fix(_partials): avoid duplicate canonical link tags
• docs(i18n): update translation key naming guidelines
• ci(workflow): optimize preview deployment cache
• refactor(assets): split theme initialization into smaller modules