AGENTS.md File: Repository Guidelines For Contributors

<general_rules> When contributing to this repository, there are several general rules to keep in mind to ensure code quality, consistency, and maintainability. These rules are designed to help developers, both new and experienced, navigate the codebase effectively and contribute in a way that aligns with the project's overall goals.

First and foremost, before introducing any new functions, always perform a thorough search within the relevant directories to check for existing functionality. This practice helps prevent code duplication and promotes the reuse of well-tested components. For instance, if you're about to create a new utility function, begin by examining the utils/ directory or other relevant modules to see if a similar function already exists. If one does, consider using or extending it rather than creating a duplicate. If a suitable function doesn't exist, create a new one, ensuring it is placed in an appropriate existing directory or, if necessary, a new directory. This approach ensures a well-organized and easily navigable codebase.

Additionally, it's crucial to adhere to the project's coding style and conventions. Consistency in code formatting is vital for readability and collaboration. Before committing any changes, run the project's linter and formatter scripts. These scripts automatically check for style issues and format the code according to the project's standards. You can typically find the commands for running these scripts in the package.json file under the scripts section. Common scripts include lint for linting and format or prettier for formatting. Running these scripts helps ensure that your code integrates smoothly with the rest of the codebase, reducing the likelihood of merge conflicts and improving overall code quality.

Moreover, strive to write clear, concise, and well-documented code. Use meaningful variable and function names, and add comments where necessary to explain complex logic or non-obvious behavior. This practice not only aids other developers in understanding your code but also helps you when revisiting your code in the future. Think of your future self and your colleagues who might need to work with your code—well-documented code saves time and reduces the chances of errors. Finally, always test your changes thoroughly. Write unit tests, integration tests, and end-to-end tests as appropriate to ensure that your code functions correctly and doesn't introduce regressions. Comprehensive testing is crucial for maintaining the stability and reliability of the project. </general_rules> <repository_structure> Understanding the repository structure is key to navigating the project effectively and making informed contributions. The repository is organized into several key directories and files, each serving a specific purpose. This high-level overview will help you quickly locate the areas of the codebase you need to work with and understand how different components interact.

At the root of the repository, you'll find essential configuration files such as package.json, which manages project dependencies and scripts, and README.md, which provides an overview of the project and instructions for getting started. These files are crucial for setting up the development environment and understanding the project's purpose. The package.json file, in particular, contains scripts for running linters, formatters, and tests, which are essential for maintaining code quality and consistency.

The main application code is typically organized into distinct directories based on functionality or modules. For instance, a common structure might include directories such as src/, lib/, or app/. Within these directories, you'll often find subdirectories representing different features or modules of the application. For example, a directory structure might look like src/components/, src/services/, and src/utils/. The components/ directory usually contains reusable UI elements, while the services/ directory might house modules for interacting with external APIs or databases. The utils/ directory typically includes utility functions that are used across the application.

Test files are usually located in a dedicated test/ or tests/ directory, often mirroring the structure of the source code. This makes it easier to locate tests for specific modules or components. For example, if you have a component located in src/components/Button.js, its corresponding test file might be located in test/components/Button.test.js. Keeping tests close to the code they test helps ensure that tests are kept up-to-date and relevant as the codebase evolves. Configuration files for tools like linters, formatters, and testing frameworks are also typically located at the root of the repository. These files, such as .eslintrc.js, .prettierrc.js, and jest.config.js, define the project's coding style, formatting rules, and testing configuration. Familiarizing yourself with these files will help you understand how the project maintains consistency and quality. </repository_structure> <dependencies_and_installation> Setting up the development environment and installing dependencies is a crucial first step for any contributor. This section provides a high-level overview of how to manage dependencies in this repository, focusing on the tools and practices used to ensure a smooth installation process. Understanding these aspects will help you get your development environment up and running quickly and efficiently.

The primary package manager used in this repository is Node Package Manager (npm). Npm is the standard package manager for Node.js projects and is used to install, manage, and update project dependencies. The project's dependencies are listed in the package.json file, which is located at the root of the repository. This file includes both development dependencies (used for tasks like testing and linting) and production dependencies (required for the application to run).

To install the project dependencies, you'll need to have Node.js and npm installed on your system. Once you have these prerequisites, you can navigate to the root of the repository in your terminal and run the command npm install. This command reads the package.json file and downloads all the necessary packages into the node_modules/ directory. It's important to run this command whenever you clone the repository or when dependencies are updated to ensure you have all the required packages.

In addition to installing dependencies, it's also essential to understand how dependencies are managed and updated. The package.json file uses semantic versioning (semver) to specify the acceptable versions of each dependency. Semver allows for flexibility in dependency updates while ensuring compatibility. Understanding the versioning scheme (e.g., ^1.2.3 or ~1.2.3) is crucial for managing potential breaking changes. When updating dependencies, it's a good practice to review the changes and test the application thoroughly to ensure that the updates haven't introduced any issues. Periodically running npm update can help keep your dependencies up-to-date, but always test after updating to maintain stability. </dependencies_and_installation> <testing_instructions> Testing is a critical part of the development process, ensuring that the codebase is robust and reliable. This section provides a general guide on testing practices within this repository, including the testing frameworks used, types of modules that should be tested, and how to run tests. By understanding these guidelines, you can contribute high-quality code and maintain the project's stability.

The primary testing framework used in this repository is Jest. Jest is a popular JavaScript testing framework known for its simplicity and ease of use. It provides a comprehensive set of tools for writing unit tests, integration tests, and end-to-end tests. Jest is often configured with tools like Enzyme or React Testing Library for testing React components, though this repository uses Jest standalone.

When writing tests, it's important to focus on testing different types of modules and components. Unit tests should be written for individual functions, classes, or modules to ensure they behave as expected in isolation. Integration tests should verify the interactions between different parts of the system, ensuring that they work together correctly. End-to-end tests should simulate user interactions to validate the overall application flow. As a general rule, any new feature or bug fix should be accompanied by appropriate tests to ensure its functionality and prevent regressions.

To run the tests, you can use the command npm test. This command executes the test scripts defined in the package.json file, which typically involves running Jest with the specified configuration. The test output will provide information about the number of tests run, the number of tests passed or failed, and any error messages. It's crucial to review the test results carefully and address any failures or warnings. Additionally, it’s helpful to run tests before committing changes to ensure that your code doesn't introduce any new issues. Consistent testing practices help maintain a high level of code quality and reliability. </testing_instructions> <pull_request_formatting> </pull_request_formatting>