Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (145 loc) · 5.34 KB

CONTRIBUTING.md

File metadata and controls

203 lines (145 loc) · 5.34 KB

Contributing to [Your Project Name]

Thank you for your interest in contributing to this project! This document outlines the project structure, setup instructions, and contribution guidelines.

📌 Project Overview

This project is a [Node.js/TypeScript/JavaScript] application with the following key features:

  • [Brief description of the project's purpose and functionality]
  • Built with [Node.js, TypeScript, etc.]
  • Uses npm for package management
  • Follows ESLint and Prettier for code style and formatting

📂 Project Structure

.
├── .github/            # GitHub-specific files (workflows, templates)
│   └── workflows/      # GitHub Actions workflows
├── src/                # Main source code
│   ├── __tests__/      # Unit and integration tests
│   ├── config.ts       # Runtime configuration (dotenv-backed)
│   ├── index.ts        # Entry point for the application
│   ├── logger.ts       # Shared logger configuration
│   ├── tools.ts        # LangChain tool definitions
│   └── ...             # Other source files
├── dist/               # Compiled output (generated by `npm run build`)
├── .env                # Environment variables (ignored in git)
├── .env.example        # Example environment variables
├── .eslintrc.js        # ESLint configuration
├── .gitignore          # Files and directories ignored by Git
├── .prettierrc         # Prettier configuration
├── CONTRIBUTING.md     # This file
├── package.json        # Project metadata and dependencies
├── README.md           # Project overview and usage
├── tsconfig.json       # TypeScript configuration
└── ...                 # Other configuration files

Key Files and Directories

File/Directory Purpose
src/config.ts Runtime configuration loaded from .env files. Avoid using process.env directly in business logic.
src/logger.ts Shared logger configuration. Logs are machine-readable and configurable via .env.
src/tools.ts Defines LangChain tools using tool(). Tools are bound in src/index.ts.
src/index.ts Entry point for the application. Binds tools using llm.bindTools(tools).
src/__tests__/index.test.ts Tests for the runtime behavior, including bindTools mocking.
.env.example Example environment variables. Keep this in sync with src/config.ts.

🛠️ Setup Instructions

Prerequisites

  • Node.js (v18 or later recommended)
  • npm (v9 or later recommended)
  • Git

Installation

  1. Clone the repository:

    git clone https://github.com/your-username/your-repo.git
cd your-repo

  2. Install dependencies:

    npm install

  3. Set up environment variables:

    • Copy .env.example to .env: 
      cp .env.example .env
    • Update .env with your local configuration.

🧪 Running Tests

This project uses Jest for testing. To run tests:

npm test

Test Coverage

To generate a coverage report:

npm test -- --coverage

🏗️ Building the Project

To compile the TypeScript code and generate the output in the dist/ directory:

npm run build

🔧 Development Workflow

Adding a New Tool

  1. Define the tool in src/tools.ts: Use the tool() function from LangChain to define the tool. Example:

    import { tool } from '@langchain/core/tools';

export const myTool = tool(
  async (args) => {
    // Tool logic here
    return { result: 'success' };
  },
  {
    name: 'my_tool',
    description: 'A tool that does something useful.',
    schema: z.object({
      input: z.string(),
    }),
  }
);

  2. Bind the tool in src/index.ts:

    import { myTool } from './tools';

const llm = ...; // Your LLM instance
llm.bindTools([myTool]);

  3. Test the tool:

    • Write unit tests in src/__tests__/index.test.ts.
    • Mock the bindTools function if necessary.

Logging

Use the shared logger from src/logger.ts:

import logger from './logger';

logger.info('This is a log message', { structured: 'data' });

📝 Commit Messages

Follow Conventional Commits for commit messages:

  • feat: add new feature
  • fix: resolve bug
  • docs: update documentation
  • chore: maintenance task

🔄 Pull Requests

  1. Fork the repository and create a new branch:

    git checkout -b feature/your-feature-name

  2. Make your changes and commit them with a descriptive message.

  3. Push to your fork and submit a pull request to the main branch.

  4. Wait for review and address any feedback.

🐛 Reporting Issues

If you encounter a bug or have a feature request, please open an issue.

📜 License

This project is licensed under the MIT License.

🙌 Acknowledgments

  • [List any dependencies, tools, or contributors you want to acknowledge]

Thank you for contributing! 🎉