AGENTS.md Guide: Repository Rules, Structure, And Contribution

by Rajiv Sharma 63 views

Contributing to a repository can be daunting, especially if you're new to the project. To make this process smoother, we've created this AGENTS.md file. Think of it as a detailed CONTRIBUTING.md tailored specifically for agents and developers, offering clear guidelines, rules, and context to help you navigate the repository effectively. This guide covers various aspects, including general coding rules, repository structure, dependencies, testing, and pull request formatting. Let's dive in!

Understanding AGENTS.md

The AGENTS.md file serves as a comprehensive guide for anyone contributing to this repository. It's designed to provide clear and concise information, ensuring that all contributors are on the same page. This file is structured into several key sections, each addressing a specific aspect of the repository and contribution process. By following the guidelines outlined in this document, you'll be able to contribute more effectively and efficiently.

Now, let’s break down each section of the AGENTS.md file.

General Rules

<general_rules> When you're writing code, especially new functions or modules, the first thing you should do is search within the src/ directory. The goal here is to see if similar functionality already exists. If something comparable is already there, you might be able to build upon it or adapt it, which saves time and keeps the codebase consistent. If nothing suitable exists, then go ahead and create your new functionality, placing it either in an existing file or a new one within the src/ directory. This helps keep the project organized and maintainable.

Before you even think about committing your code, make sure it adheres to the repository's style and linting rules. We've got some handy scripts to help you with this. These scripts ensure that your code not only works but also looks good and fits in with the rest of the project. To keep things consistent, use these scripts before every commit:

  • To format your code: yarn format
  • To check formatting: yarn format:check
  • To lint your code: yarn lint
  • To automatically fix linting issues: yarn lint:fix

By running these scripts, you’re ensuring that your code is clean, readable, and adheres to the project’s standards. This is a crucial step in maintaining a high-quality codebase. These general rules are important for maintaining code quality and consistency. </general_rules>

Repository Structure

<repository_structure> Think of this repository as a well-organized toolbox. This repository is designed as a TypeScript template project, meaning it's structured to leverage the benefits of TypeScript's strong typing and modern JavaScript features. At the heart of the project is the src/ directory. This is where all the main application logic lives. The primary entry point for the application is src/index.ts. This file is where the application starts its execution.

When the code is compiled, the output is placed in the dist/ directory. This separation of source code and compiled code helps keep the project organized. The dist/ directory is where you'll find the final, runnable version of the application.

Testing is a critical part of the development process. To ensure the reliability of the code, test files are located within the src/ directory. These files follow a specific naming convention: *.test.ts. This makes it easy to identify test files and keep them close to the code they are testing.

In summary, the repository structure is designed to be intuitive and maintainable. The src/ directory houses the application logic, dist/ contains the compiled output, and test files are located alongside their corresponding source files. Understanding this structure is crucial for navigating the codebase and making effective contributions. This high-level overview should give you a solid foundation for understanding the project's layout. </repository_structure>

Dependencies and Installation

<dependencies_and_installation> Managing dependencies is a critical aspect of any project. In this project, we use yarn as our package manager (version 3.5.1). Yarn is a fast, reliable, and secure dependency management tool that helps ensure consistency across different environments. It's important to use the correct package manager to avoid conflicts and ensure that all dependencies are installed correctly.

To get started with the project, you'll need to install all the necessary dependencies. This is a straightforward process. Simply run yarn install in the root of the repository. This command will read the package.json file, which lists all the project's dependencies, and install them into the node_modules/ directory. This process ensures that your local environment has all the libraries and tools required to run the project.

Upon the first installation, Yarn will generate a yarn.lock file. This file is crucial for ensuring that everyone working on the project uses the exact same versions of dependencies. It locks down the versions of the packages and their transitive dependencies, preventing unexpected issues caused by version mismatches. Always commit the yarn.lock file to the repository to maintain consistency across all environments. Understanding these dependencies and installation steps is key to setting up your development environment correctly. </dependencies_and_installation>

Testing Instructions

<testing_instructions> Testing is an integral part of our development workflow, ensuring the reliability and stability of the codebase. We utilize Jest and TypeScript for writing and running tests. Jest is a popular testing framework known for its simplicity and powerful features, while TypeScript ensures type safety and helps catch errors early in the development process. The configuration for Jest is managed through jest.config.js and ts-jest, providing a seamless testing experience with TypeScript.

Test files are identified by the *.test.ts suffix, making them easy to locate within the src/ directory. This naming convention helps keep tests organized and close to the code they are intended to test. It's crucial to write tests for various modules, focusing on unit tests and integration tests to cover different aspects of the application.

To run tests, we've set up several convenient commands:

  • Run all unit tests (excluding integration tests): yarn test
  • Run only integration tests: yarn test:int
  • Run a specific test file with an extended timeout (useful for debugging): yarn test:single <path/to/your/test.test.ts>

These commands provide flexibility in how you run tests, allowing you to focus on specific areas or run the entire suite. For integration tests, which often require external resources or services, it’s essential to ensure that the necessary environment is set up before running the tests.

Environment variables for tests are loaded via dotenv/config, as configured in jest.config.js. This setup allows you to manage environment-specific configurations without hardcoding them into your tests. By using environment variables, you can easily switch between different configurations for local development, testing, and production environments. Following these testing instructions will help you write effective tests and maintain a robust codebase. </testing_instructions>

Pull Request Formatting

<pull_request_formatting> To maintain consistency and clarity in our codebase, we adhere to the Conventional Commits specification for pull request titles. This standard helps us automate release management and makes it easier to understand the purpose of each pull request at a glance. By following this specification, we ensure that our commit history is clean, descriptive, and easy to navigate.

The allowed types for commit messages and pull request titles are:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit
  • release: New release

Here are a few examples of well-formatted pull request titles:

  • feat: add user authentication
  • fix(auth): resolve login issue

By using these types, we can quickly understand the nature of the changes introduced by a pull request. The optional scope (e.g., (auth)) provides additional context, making it even easier to understand the scope of the changes. Adhering to these pull request formatting guidelines ensures that our commit history remains clean and informative. </pull_request_formatting>