Repository Guidelines: Create AGENTS.md

AGENTS.md: Your Guide to Navigating this Repository

Hey there, future contributor! This document, AGENTS.md, is your go-to resource for understanding the rules, structure, and best practices within this repository. Think of it as a friendly cheat sheet to get you up to speed quickly and efficiently. We'll cover everything from general coding rules to testing procedures, ensuring you can contribute smoothly and confidently. Let's dive in and explore what makes this repository tick, making your experience as a developer a breeze. This document aims to provide clarity and guidance to make your journey into the codebase as seamless as possible. Remember, we're all about making this a welcoming and collaborative environment, so don't hesitate to reach out if you have any questions. This guide is crafted to support you every step of the way, helping you become a valuable contributor. Let's start making some awesome code together!

General Rules

<general_rules>

Coding Standards and Practices

When writing code in this repository, always adhere to the established coding style. The goal is to maintain consistency and readability across the entire codebase. Before submitting any changes, make sure your code aligns with the existing style. This ensures that the codebase remains maintainable and understandable for everyone involved. To help with this, we recommend using automated tools like linters and formatters. These tools can automatically check your code for style violations and suggest fixes.

Function and File Organization

When creating new functions or modules, start by searching within the relevant directory to see if a similar function or module already exists. This avoids code duplication and keeps things organized. If you find a suitable place, integrate your new code there. If not, create a new file or directory, ensuring the location makes logical sense within the project's structure. Make sure that the naming conventions match the existing ones. This consistency is essential for maintaining a clean and understandable codebase. Always consider the purpose and scope of your code when determining its location.

Running Scripts and Tools

Familiarize yourself with commonly used scripts such as linters and formatters. These scripts play a crucial role in maintaining code quality and consistency. Before submitting your changes, run these scripts to ensure your code complies with the repository's standards. Linters help identify potential errors, while formatters automatically adjust the code style. Ensure that all the dependencies necessary to run these scripts are installed. This will greatly improve the efficiency of your contribution and ensure the high quality of the codebase. By consistently using these tools, you help maintain a clean and well-structured project.

Error Handling and Logging

Implement proper error handling in your code. Make sure that your code gracefully handles any unexpected situations. When an error occurs, log relevant information to help with debugging. Include the error message, the context where the error occurred, and any other helpful details. This is especially important for exceptions and API calls. Proper logging makes it easier to identify and resolve issues quickly. Follow the existing logging conventions for consistency. Regularly reviewing logs can help you proactively identify and fix potential problems.

Code Reviews

During code reviews, be open to feedback and suggestions. The goal is to improve the quality of your code and to share knowledge. Take the feedback constructively, and be willing to revise your code based on the suggestions. When reviewing others' code, focus on identifying potential issues. Offer constructive feedback. Remember that code reviews are a collaborative process.

</general_rules>

Repository Structure

<repository_structure>

High-Level Overview

The repository follows a well-defined structure designed for clarity and maintainability. At the root, you'll find essential configuration files, scripts for automation, and this AGENTS.md file, which is your guide. The core of the project is organized into modular directories, each responsible for specific functionalities or components. Understanding this structure is crucial for navigating and understanding the codebase. Make sure you understand how the different directories and modules interact with each other. This understanding will significantly improve your efficiency. This modular approach ensures that changes in one part of the system have a minimal impact on others.

Key Directories and Their Purpose

• src/: This directory houses the primary source code. It is often subdivided into further directories, each representing a specific module or feature. These subdirectories contain the source files, defining classes, functions, and data structures that constitute the core application logic. This directory is the heart of the project where most of the development work takes place. The src/ directory typically aligns with the project's architectural design.
• tests/: Contains the test suite for the project, structured to mirror the src/ directory. Each test file should correspond to a source file. This structure makes it easy to find and run tests related to a specific part of the codebase. This ensures that the tests can be easily located and executed. Test cases should cover a wide range of scenarios, including both positive and negative tests, to ensure the reliability of the code.
• docs/: This directory contains documentation for the project. The documentation is an important resource for developers to learn about the project, its components, and how to use them. It should include user guides, API references, and any other relevant documentation.
• scripts/: Contains utility scripts for automating tasks such as building, testing, and deployment. These scripts streamline various development processes, helping to make the development workflow more efficient. Make sure you understand the scripts to make sure you can get your work done. These scripts can save time and effort by automating repetitive tasks.

Configuration Files

Configuration files are located at the root of the project or within specific directories to manage settings. These files control things like application behavior, environment variables, and external service connections. Understanding these files will allow you to modify configurations as needed. These files can affect the behavior of the application, and it is important to modify them with care.

</repository_structure>

Dependencies and Installation

<dependencies_and_installation>

Package Management

This project uses [Package Manager Name], which simplifies dependency management. The package manager handles the installation, update, and removal of third-party libraries and modules. Before starting any development work, it is important to ensure that you have installed the required package manager.

Installing Dependencies

To install dependencies, navigate to the root directory of the project in your terminal. Use the package manager to install the required dependencies. The command to install all the required dependencies is typically something like [Package Manager Install Command]. Ensure that you have the correct permissions to install the packages. If you encounter any issues during the installation process, refer to the package manager's documentation for troubleshooting steps. Make sure that all dependencies are installed properly before you start developing, as this is essential for the project's functionality.

Where Dependencies are Installed

Dependencies are typically installed in a specific directory or managed in a virtual environment. The specific location depends on the package manager and project setup. For instance, the dependencies may be in the node_modules directory if you're using npm or yarn. Ensure that you do not manually edit or modify files within the dependency directories, as the package manager manages these. Virtual environments are created to isolate project dependencies, which prevents conflicts between different projects. Activation and deactivation of the virtual environment will be required, depending on your development workflow.

Updating Dependencies

Keep your dependencies up to date to ensure the project has the latest features, security patches, and performance improvements. You can update the dependencies using the update command provided by the package manager.

</dependencies_and_installation>

Testing Instructions

<testing_instructions>

Testing Framework and Setup

This repository uses [Testing Framework Name] as its primary testing framework. [Testing Framework Name] provides a robust environment for writing and running tests. To set up the testing environment, ensure that you have the framework and its dependencies installed. Typically, the testing framework is included in the project dependencies, and installing those dependencies also installs the testing framework.

Types of Modules to Test

When writing tests, aim to cover the core functionality of your code. Start by testing the most important modules and functions. These tests should verify both the inputs and outputs, as well as the behavior of functions under various conditions. Include unit tests, which focus on individual components, and integration tests, which ensure that different parts of the system work together correctly. This layered approach ensures that the code behaves as expected.

Running Tests

To run tests, navigate to the root directory of the project in your terminal. Use the appropriate command for the testing framework. The command to run the test suite is typically [Testing Framework Run Command]. Tests can be run individually or as a suite. Test results and coverage reports provide insights into the codebase's quality and identify areas that need attention.

Writing Tests

When writing tests, focus on clarity, accuracy, and comprehensive coverage. Each test case should clearly describe the scenario it is testing. Use descriptive names for your test functions and assertions. Make sure that all edge cases and error conditions are tested to ensure reliability. Tests should be self-contained and easy to understand. Try to keep tests independent of each other so that the order does not affect the outcome.

Best Practices

Make sure tests are self-contained, independent, and easy to understand. Each test should focus on a single aspect of the code and should verify the output. Use clear and descriptive names for your test cases and functions. Ensure that your tests handle all edge cases and error conditions, providing comprehensive coverage. Test driven development (TDD) helps to write better code by providing the means of writing a test before the actual implementation. Use mocks and stubs to isolate the code under test, avoiding dependencies on external resources.

</testing_instructions>

Pull request formatting

<pull_request_formatting>

</pull_request_formatting>