Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• biome.json
• package.json
• README.md
• scripts/new-post.js
• src/content/posts/2018-10-30/Charlotte-Markdown.md
• src/content/config.ts

This guide provides instructions and best practices for contributing to the Charlotte project. Following these guidelines helps maintain code quality, consistency, and ensures that your contributions can be smoothly integrated. The guide covers setting up the development environment, the code submission process, styling standards, and how to create new content.

Sources: CONTRIBUTING.md, README.md

Getting Started

Before you begin, ensure your development environment meets the project's requirements.

Environment Requirements

The project requires specific versions of Node.js and pnpm to ensure compatibility and consistent dependency management.

Tool	Version
Node.js	>= 22
pnpm	>= 9

After cloning the repository, install the necessary dependencies using the following command:

pnpm install

Sources: README.md:20-22, README.md:28

Development Workflow

The project includes several scripts to aid in development, building, and code quality checks.

Common Commands

The following table lists the most frequently used commands for development. These are defined in the scripts section of package.json.

Command	Description
pnpm dev	Starts the local development server.
pnpm build	Builds the project for production.
pnpm preview	Previews the production build locally.
pnpm check	Runs TypeScript type checking using astro check.
pnpm format	Formats the entire /src directory using Biome.
pnpm lint	Checks and fixes code style issues in /src using Biome.
pnpm new-post <name>	Creates a new blog post markdown file.
pnpm clean	Removes cache files from .astro, dist, and node_modules/.vite.

Sources: README.md:25-37, package.json:5-16

The following diagram illustrates the typical development cycle.

This diagram shows the standard workflow for a developer contributing code.
Sources: README.md:25-37, CONTRIBUTING.md:18-22

Submitting Code

To ensure a clear and manageable contribution history, please adhere to the following process when submitting code.

Contribution Process

1. Discuss Major Changes: Before starting work on new features or significant design changes, open an issue or discussion to align with the project's direction.
2. Focused Pull Requests: Each pull request should address a single, specific purpose. Avoid mixing unrelated changes.
3. Conventional Commits: Use the Conventional Commits format for your commit messages. This helps maintain a clear and consistent git history.
4. Code Quality Checks: Before submitting, run the check and format commands to ensure your code is error-free and adheres to the project's style.

pnpm check
pnpm format

The diagram below outlines the recommended contribution flow.

This flowchart visualizes the end-to-end process for contributing to the project.
Sources: CONTRIBUTING.md:5-16

Code Style and Quality

The project enforces a consistent code style using Biome. The core principles are simplicity, adherence to modern web standards, and avoiding over-engineering.

Sources: CONTRIBUTING.md:24-26

Linting and Formatting

Biome is configured in biome.json to format code and enforce linting rules.

• Indentation: Tabs are used for indentation.
• Quote Style: Double quotes (") are used for JavaScript/TypeScript files.
• File Scope: Formatting and linting apply to all files except those specified in the ignoreUnknown and includes sections, such as .css files and the dist directory.

{
	"formatter": {
		"enabled": true,
		"indentStyle": "tab"
	},
	"linter": {
		"enabled": true,
		"rules": {
			"recommended": true,
			"style": {
				"noParameterAssign": "error",
				"useAsConstAssertion": "error",
				"useSelfClosingElements": "error",
				"useSingleVarDeclarator": "error",
				"noInferrableTypes": "error"
			}
		}
	},
	"javascript": {
		"formatter": {
			"quoteStyle": "double"
		}
	}
}

This snippet from biome.json shows key formatter and linter configurations.
Sources: biome.json:13-41

Creating New Content

A primary way to contribute is by adding new blog posts. The project provides a script to streamline this process.

Creating a New Post File

You can create a new post using a pnpm script, which generates a Markdown file with the necessary frontmatter.

pnpm new-post <filename>

This command executes scripts/new-post.js. The script performs the following actions:

1. Checks if a filename is provided.
2. Appends a .md extension if not present.
3. Verifies that a file with the same name doesn't already exist in src/content/posts/.
4. Creates the directory if it doesn't exist.
5. Writes a new Markdown file with a pre-populated frontmatter template.

The following sequence diagram illustrates this process.

This diagram shows the interaction between the user, the script, and the file system when creating a new post.
Sources: scripts/new-post.js, README.md:41-44

Post Frontmatter

All posts must include frontmatter metadata at the top of the Markdown file. The fields are defined in src/content/config.ts and an example is available in the Markdown guide.

Attribute	Type	Description
title	string	The title of the post.
published	date	The publication date of the post.
updated	date (optional)	The date the post was last updated.
description	string	A short summary of the post, displayed on the homepage.
image	string	The path to the cover image. Can be a relative path, a path from /public, or an external URL.
tags	string[]	A list of tags associated with the post.
category	string	The category of the post.
draft	boolean	If true, the post will not be displayed on the production site. Defaults to false.
isPinned	boolean	Set automatically if the post slug is listed in siteConfig.pinnedPost. Do not set manually.

Sources: src/content/posts/2018-10-30/Charlotte-Markdown.md:3-12, src/content/config.ts:4-16

The new-post script generates the following template:

---
title: ${args[0]}
published: ${getDate()}
description: ''
image: ''
tags: []
category: ''
draft: false 
lang: ''
---

Sources: scripts/new-post.js:34-44