Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (101 loc) · 6.41 KB

CONTRIBUTING.md

File metadata and controls

145 lines (101 loc) · 6.41 KB

Contributing to LikeC4

First of all, thank you for showing interest in contributing to LikeC4! All your contributions are extremely valuable!

Ways to contribute

  • Improve documentation: Fix incomplete or missing docs, bad wording, examples or explanations.
  • Give feedback: We are constantly working on making LikeC4 better. Please share how you use LikeC4, what features are missing and what is done well via GitHub Discussions or Discord.
  • Share LikeC4: Share links to the LikeC4 docs with everyone who might be interested!
  • Contribute to the codebase: Propose new features via GitHub Issues, or find an existing issue that you are interested in and work on it!
  • Give us a code review: Help us identify problems with the source code or make LikeC4 better.

Contributing workflow

  • Decide on what you want to contribute.
  • If you would like to implement a new feature, discuss it with the maintainers (GitHub Discussions or Discord) before jumping into coding.
  • After finalizing issue details, you can begin working on the code.
  • Run tests with pnpm test and submit a PR once all tests have passed.
  • Get a code review and fix all issues noticed by the maintainer.
  • If you cannot finish your task or if you change your mind – that's totally fine! Just let us know in the GitHub issue that you created during the first step of this process. Our community is friendly – we won't judge or ask any questions if you decide to cancel your submission.
  • Your PR is merged. You are awesome ❤️!

Get started with LikeC4 locally

  1. Fork the repository, then clone or download your fork.

  2. Project requires Node.js >=22.21.1 and pnpm
    See required versions in .tool-versions

    • (Optional) If you use asdf:

      asdf install

  3. Install dependencies with pnpm:

    pnpm install

  4. Pre-generate sources by running build (or generate) in root:

    pnpm build
# or
pnpm generate

[!TIP] Tip on TypeScript Project uses Typescript project references to optimize compile time, but sometimes it may cause issues on delete/rename.

It is always a good idea to run pnpm generate after checkout or merge.

Try pnpm clean in root to clean up caches, and pnpm typecheck after.

If it doesn't help, try pnpm store prune, remove node_modules, and clean pnpm install.

  1. Mostly used dev tasks:

    • pnpm dev in apps/playground
      This command starts the playground app in development mode, picking up changes from any package with hot reloading.
    • pnpm dev (or any pnpm dev:*) in package/likec4
      This command also picks up changes from any package.
    • pnpm vitest:ui in root to run all tests.
    • pnpm typecheck in root to run the typecheck.

  2. To work on VSCode extension:

    • Launch Run Extension to start a new VSCode instance with the extension loaded.

[!TIP] Tip on VSCode extension development If you work mostly on vscode-preview package, you don't need to restart Run Extension when you make changes.
Keep pnpm dev in vscode-preview running, VSCode will pick up changes when close-open the panel.

E2E

/e2e contains isolated workspace to run E2E tests.

To run locally, from root:

pnpm test:e2e

What it does:

  • pack likec4 to tarball
  • install this tarball in isolated wokspace
  • generate spec files from model (using LikeC4Model)
  • run playwright

About this repository

Top-level layout

This repository's contents are:

  • /apps/docs Astro-app, contains the content for our docs site at likec4.dev
  • /apps/playground - Vite SPA, site playground.likec4.dev
  • /packages contains the source for packages

Packages

/packages/likec4

  • Purpose: Provides CLI, Vite plugin, generates static website (sources in /packages/likec4/app/). Main entry point for the tool.
  • Technology: Uses yargs, Vite

Core /packages/core

  • Purpose: Core type definitions, api, model builder and utilities. compute-view contains logic for computing diagram views. Read core's README.

  • Technology: Pure TypeScript, no frameworks. Heavy use of generators and remeda

  • Suggestions: A great way to start contributing is by adding more tests for compute-view. This will help you understand how it works while also benefiting the project. There are also open questions from @pavelpykhtin, who has made significant contributions.

Diagrams /packages/diagram

Generators /packages/generators

  • Purpose: Converts LikeC4 Model to other formats, like Mermaid, PlantUML, SVG, etc.
    Also generates typings for Model API and React.

Language Server /packages/language-server

  • Purpose: Parses DSL, builds models, and computes views
  • Technology: Built with Langium

Layouts /packages/layouts

  • Purpose: Transforms computed views into visual graph layouts
  • Technology: Uses Graphviz for layout algorithms

VSCode Extension /packages/vscode

Additional Packages

  • create-likec4: Scaffolding tool for new projects
  • icons: Pre-bundled icon sets
  • log: Common logger implementation
  • tsconfig: TypeScript configuration
  • vscode-preview: Preview panel component for VS Code extension