Contributing

Thank you for considering contributing to Norgolith, as the only maintainer of the project I appreciate it very much! This guide will walk you through the development setup, coding standards, and contribution workflow.

Development Setup

Nix Development Environment

Norgolith provides a Nix flake for a reproducible development environment. This is the recommended setup.

Install Nix

If you don’t have Nix installed, follow the official installation guide.

Enable Flakes

Ensure flakes are enabled in your Nix configuration:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Enter the Development Shell

nix develop

This will provide an interactive shell with all dependencies pre-installed.

Build and Test

cargo build
cargo nextest run --test-threads=1

Tip

If you are testing changes that require an existing Norgolith site, you could create a new site called my-site in Norgolith’s project root directory, my-site is gitignored so there won’t be any risk of git adding it per accident.

Optional: Nix-Direnv Integration

For automatic development environment activation, use nix-direnv.

Manual Setup

If you prefer not to use Nix, you can set up the environment manually:

Install Rust

Install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Dependencies

Ensure you have the following installed:

• cargo: Rust’s package manager (comes with rustup).

• rust-analyzer: Rust Language Server (optional but recommended, rustup component add rust-analyzer).

• cargo-nextest: Next-generation test runner for Rust projects (optional but recommended).

Clone the Repository

git clone https://github.com/NTBBloodbath/norgolith.git \
&& cd norgolith

Build and Test

cargo build
# 'cargo nextest run --test-threads=1' if you've installed cargo-nextest
cargo test -- --test-threads=1

Coding Standards

Rust Code Style

• Follow the Rust API Guidelines.

• Use rustfmt to format your code before pushing your changes:

cargo fmt

• Use clippy for linting:

cargo clippy

Documentation

• Document public APIs using Rustdoc.

• Include examples in your documentation where applicable.

Git Workflow

Feature Branch Workflow

Follow the Feature Branch Workflow.

git checkout -b feat/your-feature-name

Commit Your Changes

Follow the Conventional Commits guidelines.

Push Your Branch

git push origin feat/your-feature-name

Create a Pull Request

Open a PR against the master branch.

Conventional Commits

Norgolith follows the Conventional Commits specification. This ensures a consistent commit history and enables automated changelog generation.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer]

Common Types

• feat: A new feature.

• fix: A bug fix.

• hotfix: A critical bug fix.

• docs: Documentation changes.

• style: Code style changes (formatting, linting).

• perf: Performance changes.

• refactor: Code refactoring.

• test: Adding or updating tests.

• chore: Maintenance tasks.

• ci: CI/CD changes.

• revert: Revert changes.

Example Commit Messages

feat(templates): add support for dark mode

fix(converter): handle edge case in norg syntax

docs: update contributing guide

Testing Guidelines

Running Tests

Avoid running tests with parallelism, this can cause issues with some of them. Running the tests using one thread will take a little longer, but the tests won’t interfere with each other if they share state.

cargo test -- --test-threads=1

Note

Try to use cargo nextest whenever possible for getting a better output.

Writing tests

• Use Tokio’s test framework.

• Include unit tests for individual functions.

Pull Request Process

Fork the Repository

Fork the Norgolith repository to your GitHub account.

Create a Feature Branch

Follow the Feature Branch Workflow.

Submit a Pull Request

• Ensure your PR includes a clear title and description of the changes.

• Reference any related issues.

• Ensure your commits follow the Conventional Commits conventions.

• Squash any non-relevant commit message (e.g. fixes to your own Pull Request code) to keep the commit history as clean as possible.

Code Review

• Address any feedback from reviewers. Please try to use Conventional Comments whenever possible while reviewing code.

• Update your PR as needed.

Merge

Once approved, your PR will be merged into master.

Community Standards

Code of Conduct

Norgolith follows the Rust Code of Conduct. Please adhere to it in all interactions.

Communication

• Join the Neorg community on Discord for discussions in the #norgolith channel.

• Use GitHub Issues for bug reports and feature requests. Please use the issues templates whenever possible.

Note

Feel free to bug me on the Discord community @ntbbloodbath if you have any question, need guidance or prefer a real-time communication while debugging/implementing something in the codebase. I’ll be glad to give you a hand!

Do you want to start contributing?

Check out the issue tracker for open tasks. I try to assign priorities, scopes and milestones to the issues so that they are easier to identify.

Any contribution is welcome, and thanks again for your interest in helping with the project! 💜