Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
185 lines (113 loc) · 7.06 KB

CONTRIBUTING.md

File metadata and controls

185 lines (113 loc) · 7.06 KB

Contribution Guide

Thank you for your interest in contributing to Farm!. Before submitting your contribution, please make sure to take a moment and read through the following guidelines.

Code of Conduct

All contributors are expected to follow our Code of Conduct.

Bug reports

As farm is currently in the process of rapid development iteration, some unexpected problems may be encountered in the process of development.

We can't fix what we don't know about, so please report problems and unexpected behavior.

You can open a new issue by following new-issues and choosing one of the issue templates.

Feature requests

Please feel free to open an issue using the feature request template.

Pull Request Guidelines

  • Please adhere to the code style that you see around the location you are working on.

  • Setup Your Development Environment.

  • Checkout a topic branch from a base branch, e.g. main .

  • Run cargo test and make sure that it passes.

  • If you've changed some packages And prepare for an updated version, you should output npx changeset in the root directory. we should try our best to keep releasing the patch version. If there are no major changes, please choose to update the patch version.

  • When you are done with your work, verify that it works locally with pnpm run ready

Setup

  • Fork and clone the repo.

  • Create a branch for your PR with git checkout -b your-branch-name.

  • To keep main branch pointing to remote repository and make pull requests from branches on your fork. To do this, run:

  git remote add upstream https://github.com/farm-fe/farm.git
  git fetch upstream
  git branch --set-upstream-to=upstream/main main

Development Environment Setup

Dependencies

IDE

We recommend that you use vscode for development and recommend two necessary plugins that you need to install

  • rust-analyzer support rust language
  • biome farm use biome to detect and format the code

You can install them in the extension

Setup Other Dependencies

  • Install protoc for building sass-embedded.

TIP: When you run pnpm bootstrap and you use mac or linux systems, farm will automatically install protoc for you system

Start running

Farm development is very simple. You only need to execute pnpm bootstrap in the root directory for development.

$ pnpm bootstrap

  • use pnpm bootstrap to install dependencies and build core packages with series of initialization operations.

  • Work with examples (open a new terminal): cd examples/react && pnpm start, report an issue if the example does not start normally.

  • If examples/react project runs successfully, the development environment has been configured successfully

  • If you changed Rust code in crates, run npm run build:rs under packages/core again to get the latest binary.

When you are developing node side code, the root directory executes pnpm start to debug the code in real time, and when you are developing rust side code, the root directory executes pnpm start:rs to debug the code in real time.

// node side
pnpm start

// rust side
pnpm start:rs

Testing

We also need to test two parts, a set of Rust tests and a set of Node tests. Make sure all the tests pass before you submit the code.

Rust Testing

  • Input cargo test in the root directory will run all the test cases.
# root path or crates path
cargo test

If you want to update snapshot, you can use INSTA_UPDATE=always cargo test

INSTA_UPDATE=always cargo test

Node Testing

  • Input pnpm test in the root directory to run all test cases based on vitest.
# root path
pnpm test

Quickly create plugins through scaffold

If you want to develop a plugin for farm, farm provides a scaffolding to help you quickly create a plugin, which you can create with the following command. You can go to the cd packages/ cli directory, run npm link or global installation @ farmfe/ cli to use this CLI, after the installation is complete, You can create a plugin through farm plugin create. Farm supports the creation of rust and js plugins.

$ farm plugin create <plugin-name> # create a plugin support js or rust

Pull Request Preface Tip

Farm is divided into two parts: the JavaScript side and the Rust side:

  • the JavaScript side: see code in the packages directory. contains core (dev server, file watcher, and compiler wrapper), CLI, runtime, and runtime plugins (module system, HMR).
  • the Rust side: see code in the crates and rust-plugins directory. contains core (compilation context, plugin drivers, etc.), compiler (compile process, HMR update, etc.), and plugins.

AI-Assisted Development

Farm's repository is configured with a set of AI agent skills and instructions to help contributors work more effectively. These are available when using VS Code with GitHub Copilot.

Agent Instructions

The AGENTS.md file at the repository root provides project-level context to any AI coding assistant. It covers the repo structure, key commands, conventions, and guardrails. Read it before relying on agent suggestions.

Slash Commands (Skills)

Type / in Copilot Chat to access workflow-specific slash commands:

Command What it does
/git-commit-push Safely stages, commits, and pushes changes with guardrails
/farm-ready-gate Runs pnpm run ready — the full CI gate — and reports any failing step
/opsx:propose Drafts a new change proposal with design and task artifacts
/opsx:apply Implements tasks from an OpenSpec change
/opsx:explore Opens a thinking-partner explore session (read-only)
/opsx:archive Archives a completed change

Skills live in .github/skills/ (project-shared) and .agents/skills/ (agent utilities). See AGENTS.md §Skills for the full list and instructions for creating new ones.

AI Agents

A FarmFE Docs Sync agent (.github/agents/farmfe-docs-sync.agent.md) is available for keeping documentation in sync with code changes. Invoke it after modifying any public API, config option, or plugin interface.

Rust-Specific AI Guidance

The rust-engineer and rust-best-practices skills (.agents/skills/) provide idiomatic Rust guidance aligned with this codebase. They are auto-suggested when working in crates/ or rust-plugins/.

What AI Should Not Do

Copilot and other agents are instructed not to:

  • Force-push or hard-reset without explicit approval.
  • Edit generated files (dist/*.d.ts, typed-router.d.ts, auto-imports.d.ts).
  • Modify pnpm-lock.yaml directly.
  • Bypass hooks with --no-verify.

If an AI suggestion violates these, reject it and report the case.