Skip to content

Latest commit

 

History

History
149 lines (108 loc) · 5.94 KB

CONTRIBUTING.md

File metadata and controls

149 lines (108 loc) · 5.94 KB

Contributing guidelines

First off, a huge thank you for considering contributing to this project! I am incredibly grateful for your interest in making this project even better, and allowing developers to build better chat features in their projects.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, we will reciprocate that respect by addressing your issue and assisting you finalize your pull requests.

Prerequisites

Before contributing, ensure you have the following installed:

  • Node.js (v18 or higher)
  • npm

Familiarity with the following tools is recommended:

  • Turborepo
  • React and Next.js
  • semantic-release

Table of Contents

  1. Monorepo Structure
  2. Versioning with semantic-release
  3. How the CLI Package Works
  4. Development Workflow
  5. Making Your First Contribution

Monorepo

This is a monorepo powered by turborepo split into the following:

  • apps/:
    • www/: The primary web app showcasing some of the features, built with Next.js
    • docs/: The documentation site, built with Nextra
  • examples/: A folder to showcase example apps - such as chatbots etc.
  • packages/:
    • cli/: The npm package that gets published to npm, making it possible to run npx shadcn-chat-cli add
    • ui/: This package is used as a shared ui dependency package in the www and docs.

semantic-release

This project uses semantic-release to automate version management and package publishing on npm.

When changes are made to specific paths in the repository on a pull request, a GitHub action determines whether to trigger a patch, minor, or major release.

Paths Monitored for Changes:

  • 'apps/www/public/registry/index.json'
  • 'packages/cli/\*\*'
  • 'packages/ui/**'

To ensure proper versioning, follow the commit message formats when making changes to the chat components. If you're unsure, avoid prefixing your commit message with any of the semantic keywords (e.g., feat:, fix:, BREAKING CHANGE:).

How the project works

CLI package overview

The cli package is a command-line tool that fetches components from a registry. This registry is a JSON file containing metadata about available components, such as their names, dependencies, files, and types. The registry is hosted on the web app and can be found at here.

Registry structure

Each component in the registry includes the following fields, which are used by the cli tool to install them:

  • name: The name of the component.
  • dependencies: A list of other components it depends on.
  • files: The files that make up the component (e.g., .tsx, .ts).
  • type: The type of component (e.g., components:ui or hooks).

Development workflow

Making Changes to Chat Components

All chat components are maintained in the shared UI package (packages/ui/src/components/ui/chat). Follow these steps to make changes:

  1. Navigate to the Shared UI Package: 
    cd packages/ui
  2. Make your changes:
    • Edit the components in the src/components/ui/chat directory, or create new ones
    • For example, update the ChatBubble component in src/components/ui/chat/ChatBubble.tsx.
  3. Rebuild the Shared UI Package:
    • After making changes, rebuild the package to ensure the updates are reflected:
    npm run build
    • You can now import the components in the frontend (www or docs):
    import { ChatBubble } from "@shadcn-chat/ui";
  4. Test Your Changes Locally:
    • Start the dev server by changing directory to the root folder and run
    npm run dev
    • Verify the changes are applied correctly
  5. Update the registry
    • If you’ve added or modified components, regenerate the registry to update the metadata, by changing directory to the root folder and run
    npm run generate-registry

Testing the CLI in Development Mode

To test your newly generated registry changes locally with the npx command, do the following:

  1. Navigate to the CLI Package:

    cd packages/cli

  2. Run the CLI in Development Mode: Use the start:dev script to run the CLI with a local registry:

    npm run start:dev add

  3. Check the file(s): The above will add the files to a packages/cli/src/components/ui/chat folder. This is just to test, if the CLI command works as expected.

    Make sure to check if the files are correct, and then delete them after!

This project uses Prettier to maintain code quality. Before committing, ensure your code passes linting and formatting checks: npm run format

Pull requests

Following these guidelines ensures a smooth and efficient process for everyone involved. To contribute:

  1. Create your own fork of the repository
  2. Do the changes in your fork
  3. Open a pull request when you feel like the changes are finished.

This lets us review your work and discuss any necessary adjustments.

Make sure to follow a semantic commit message style.

Example of a PR:

feat: add voice input support
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: feat, fix, refactor, style, chore, docs or test.```

First time opening a PR? Check this out.

Thank you again for your contribution! 🎉