Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
298 lines (183 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

298 lines (183 loc) · 10.4 KB

Contributing

The following documentation is only for the maintainers of this repository.

Monorepo setup

This repository is managed as a monorepo with PNPM workspace to handle the installation of the npm dependencies and manage the packages interdependencies.

It's important to note that PNPM workspace doesn't hoist the npm dependencies at the root of the workspace as most package manager does. Instead, it uses an advanced symlinked node_modules structure. This means that you'll find a node_modules directory inside the packages folders as well as at the root of the repository.

The main difference to account for is that the devDependencies must now be installed locally in every package package.json file rather than in the root package.json file.

Turborepo

This repository uses Turborepo to execute its commands. Turborepo helps save time with its built-in cache but also ensures the packages' topological order is respected when executing commands.

To be understand the relationships between the commands, have a look at this repository turbo.json configuration file.

Project overview

This project is split into two major sections, packages/ and samples/.

Packages

Under packages/ are the actual telemetry libraries.

Samples

Under samples/ are applications to test the loggers functionalities while developing.

You'll find four samples:

  • web: A sample application for testing web loggers.

Installation

This project uses PNPM workspace, therefore, you must install PNPM:

To install the project, open a terminal at the root of the workspace and execute the following command:

pnpm install

Setup environment variables

Ids, keys and tokens must set to send data to the different development environment of the telemetry platforms.

First, create a file named .env.local at the root of the workspace:

workspace
├── package.json
├── .env.local

Then, add the following key/values to the newly created .env.local file:

  • LOGROCKET_APP_ID: The application id of the frontend-platform-team-dev LogRocket project.

Note

The .env.local file is configured to be ignored by Git and will not be pushed to the remote repository.

Setup Retype

Retype is the documentation platform that this repository is using for its documentation. As this project is leveraging a few Pro features of Retype.

Everything should work fine as-is but there are a few limitations to use Retype Pro features without a wallet with a licence. If you want to circumvent these limitations, you can optionally, setup your Retype wallet.

To do so, first make sure that you retrieve the Retype license from your Vault (or ask IT).

Then, open a terminal at the root of the workspace and execute the following command:

npx retype wallet --add <your-license-key-here>

Develop the packages

Open a VSCode terminals and start one of the sample application with one of the following scripts:

pnpm dev-web

You can then open your favorite browser and navigate to http://localhost:8080/ to get a live preview of your code.

LogRocket

The sample applications' telemetry data is sent to the frontend-platform-team-dev project in LogRocket.

Release the packages

When you are ready to release the packages, you must follow the following steps:

  1. Run pnpm changeset and follow the prompt. For versioning, always follow the SemVer standard.
  2. Commit the newly generated file in your branch and submit a new Pull Request(PR). Changesets will automatically detect the changes and post a message in your pull request telling you that once the PR closes, the versions will be released.
  3. Find someone to review your PR.
  4. Merge the Pull request into main. A GitHub action will automatically trigger and update the version of the packages and publish them to npm. A tag will also be created on GitHub tagging your PR merge commit.

Troubleshooting

GitHub

Make sure you're Git is clean (No pending changes).

npm

Make sure GitHub Action has write access to the selected npm packages.

Compilation

If the packages failed to compile, it's easier to debug without executing the full release flow every time. To do so, instead, execute the following command:

pnpm build

By default, packages compilation output will be in their respective dist directory.

Update the agent skill

By default, the sync-agent-skill workflow updates the skill automatically. If changes are required, it opens a pull request with the appropriate modifications.

If the workflow does not behave as expected, the simplest way to update an agent skill is to use an agent:

  1. Start your preferred agent.
  2. Copy the content of UPDATE_SKILL.md into the agent prompt.
  3. Commit the changes and merge the pull request.

NOTE: Skills installed using skills.sh are sourced directly from the repository files. Merging the pull request is therefore sufficient to update the installed skill.

Workflows

The following workflows are available with GitHub:

Workflow File Trigger Purpose
CI .github/workflows/ci.yml Push to main, PRs Build, lint, typecheck, test
Changeset .github/workflows/changeset.yml Push to main Version bumps and npm publish
PR packages .github/workflows/pr-pkg.yml PRs Publish preview packages
Update dependencies .github/workflows/update-dependencies.yml Weekly (Tue 14:00 UTC) Automated dependency updates
Code review .github/workflows/code-review.yml PRs Automated code review
Claude .github/workflows/claude.yml @claude mentions Interactive AI assistance
Sync agent skill .github/workflows/sync-agent-skill.yml Push to main (docs/) Sync logging skill with docs
Retype .github/workflows/retype-action.yml Push to main, PRs Build and deploy documentation site
Audit monorepo .github/workflows/audit-monorepo.yml First day of month Best practices audit
Update agent docs .github/workflows/agent-docs.yml Push to main Sync agent-docs/ with docs and code

Commands

From the project root, you have access to many commands the main ones are:

dev-web

Start a watch process for the "web" sample application.

pnpm dev-web

dev-docs

Start the Retype dev server. If you are experiencing issue with the license, refer to the setup Retype section.

pnpm dev-docs

build-pkg

Build the packages for release.

pnpm build-pkg

lint

Lint the packages files.

pnpm lint

test

Run the packages unit tests.

pnpm test

changeset

To use when you want to publish a new package version. Will display a prompt to fill in the information about your new release.

pnpm changeset

clean

Clean the shell packages (delete dist folder, clear caches, etc..)

pnpm clean

reset

Reset the monorepo installation (delete dist folders, clear caches, delete node_modules folders, etc..)

pnpm reset

list-outdated-deps

Checks for outdated dependencies. For more information, view PNPM documentation.

pnpm list-outdated-deps

update-outdated-deps

Updated outdated dependencies to their latest version. For more information, view PNPM documentation.

pnpm update-outdated-deps

CI

We use GitHub Actions for this repository.

You can find the configuration is in the .github/workflows folder and the build results are available here.

We currently have 2 builds configured:

Changesets

This action runs on a push on the main branch. If there is a file present in the .changeset folder, it will publish the new package version on npm.

CI

This action will trigger when a commit is done in a PR to main or after a push to main. The action will run build, lint and test commands on the source code.

Retype

This action will trigger when a commit is done in a PR to main or after a push to main. The action will generate the documentation website into the retype branch. This repository Github Pages is configured to automatically deploy the website from the retype branch.

Add a new package to the monorepo

There are a few steps to add new packages to the monorepo.

Before you add a new package, please read the Workleap GitHub guidelines.

Create the package

First, create a new folder matching the package name in the packages directory.

Open a terminal, navigate to the newly created directory, and execute the following command:

pnpm init

Answer the CLI questions.

Once the package.json is generated, please read again the Workleap GitHub guidelines and make sure the package name, author and license are valid.

Don't forget to add the npm scope "@workleap" before the package name. For example, if the project name is "foo", your package name should be "@workleap/foo".

Make sure the package publish access is public by adding the following to the package.json file:

{
  "publishConfig": {
    "access": "public"
  }
}

Dependencies

npm dependencies and peerDependencies must be added to the package own package.json file.