Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
215 lines (145 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

215 lines (145 loc) · 10.8 KB
Raw

Contributing Guide

Thank you for your interest in contributing to this project! We value and appreciate any contributions you can make.

To maintain a collaborative and respectful environment, please consider the following guidelines when contributing to this project.

Prerequisites

How to Contribute

  1. Open an issue to discuss and gather feedback on the feature or fix you wish to address.
  2. Fork the repository and clone it to your local machine.
  3. Create a new branch to work on your contribution: git checkout -b your-branch-name.
  4. Make the necessary changes in your local branch.
  5. Ensure that your code follows the established project style and formatting guidelines.
  6. Perform testing to ensure your changes do not introduce errors.
  7. Make clear and descriptive commits that explain your changes.
  8. Push your branch to the remote repository: git push origin your-branch-name.
  9. Open a pull request describing your changes and linking the corresponding issue.
  10. Await comments and discussions on your pull request. Make any necessary modifications based on the received feedback.
  11. Once your pull request is approved, your contribution will be merged into the main branch.

Contribution Guidelines

  • All contributors are expected to follow the project's code of conduct. Please be respectful and considerate towards other contributors.
  • Before starting work on a new feature or fix, check existing issues and pull requests to avoid duplications and unnecessary discussions.
  • If you wish to work on an existing issue, comment on the issue to inform other contributors that you are working on it. This will help coordinate efforts and prevent conflicts.
  • It is always advisable to discuss and gather feedback from the community before making significant changes to the project's structure or architecture.
  • Ensure a clean and organized commit history. Divide your changes into logical and descriptive commits.
  • Document any new changes or features you add. This will help other contributors and project users understand your work and its purpose.
  • Be sure to link the corresponding issue in your pull request to maintain proper tracking of contributions.

Development

This project is a monorepo using Nx and NPM. We also make heavy use of NPM Workspaces. All code is located on the /code folder.

Weave.js is separated in several packages for better maintainability, these packages are located on the code/packages folder:

  • create-backend-app: Helper package that contains the CLI to create the backend test app.
  • create-frontend-app: Helper package that contains the CLI to create the frontend test app.
  • react: Package that contains the helper to use Weave.js with React.
  • sdk: Main package of Weave.js, contains the SDK.
  • store-azure-web-pubsub: Package that contains the client / server side of a Store that uses Azure Web PubSub as transport.
  • store-websockets: Package that contains the client / server side of a Store that uses Websockets as transport.
  • types: Package that contain all the TS typings for the project.

Installation

Before start we need to install all the dependencies to work with the monorepo, this is done by executing the following command from the /code folder.

npm install

Frontend & Backend Setup

Is good practice to setup a backend and frontend application on your local development environment that you can use to develop & test the changes made to the different packages that your PR touches. Our create-app CLI can help with this, just follow the quickstart located in or documentation.

Development Tasks

Once you have a backend and frontend to test locally the changes on the different packages, you can perform several operations on top of the different packages:

  • build: build the package.
  • lint: lints the package.
  • format: formats the package using prettier.
  • link: links the package.
  • test: test the package (*).

(*): as today not all packages contain unitary tests

All this operations can be performed:

  • Per package, just launch the following command:

    npm run <operation> --workspace=<package-name>

    Where <package-name> is the name of the package you want to build. You can find the package name in the package.json file, attribute name of each /code/packages/* folder.

  • All packages:

    npm run <operation>

All commands are launched from the /code folder.

Development Flow

For start:

  1. Setup your test backend & frontend.

  2. Install the monorepo dependencies.

  3. Build all the packages.

  4. Link all the packages.

  5. On the backend / frontend project run:

    npm link @inditextech/<package-name> @inditextech/<package-name-2> ...

    To link the built packages and use this instead of installed from NPM.

  6. Start your backend, this will use the built linked packages.

  7. Before starting the frontend, setup the following environment variables:

    1. WEAVE_KONVA_PATH, that points to the konva instance of your node_modules folder: <project_path>/code/node_modules/konva.
    2. WEAVE_YJS_PATH, that points to the yjs instance of your node_modules folder: <project_path>/code/node_modules/yjs.

  8. Start your frontend, this will use the built linked packages and will also use a single instance of konva and yjs packages.

To make a change and test it:

  1. Make a change on a package or packages related to the Feature of Fix you're trying to solve.
  2. Build the package or packages.
  3. Refresh your frontend or backend - depending on the change performed, and test the change.

As you can see to test you can repeat steps 1-3 as many times as you want.

Before Submitting

  • Lint your code with npm run lint.

  • Format your code with npm run format.

  • Update the CHANGELOG.md to reflect the changes you made, we follow Conventional Commits.

    • Add your entry under ## [Unreleased], in the ### Added / ### Changed / ### Fixed section that matches your change (create the section if it isn't there yet).
    • Format: - [#ISSUE_ID](https://github.com/InditexTech/weavejs/issues/ISSUE_ID) ISSUE_NAME, where ISSUE_NAME is the verbatim title of the GitHub issue (drop a generic prefix like Feature request:/Bug: if the issue has one, but otherwise don't paraphrase or summarize it).
    • Example: - [#1158](https://github.com/InditexTech/weavejs/issues/1158) Opt-in "fully enclosed" (contains) mode for drag-selection

  • On the PR, depending on your change add one of the following labels:

    • skip-release: when this PR is merged no release will be performed.
    • release-type/major: when this PR is merged a major release will be performed.
    • release-type/minor: when this PR is merged a major release will be performed.
    • release-type/patch: when this PR is merged a patch release will be performed.
    • release-type/hotfix: when this PR is merged a hotfix release will be performed.

  • Document your changes, check the Documentations section of this document.

Documentation

This project documentation is built with Antora via docouture and NPM. All code is located on the /docs folder.

Documentation is based on AsciiDoc and the content files are located on /docs/src/modules/<module>/pages, one page per file. Every page must have a corresponding xref: entry in that module's nav.adoc, or it builds but stays unreachable from the navigation.

Installation

Before start making changes to the documentation we need to install all the dependencies to work with it, this is done by executing the following command from the /docs folder.

npm install

Documentation Tasks

Once you have a backend and frontend to test locally the changes on the different packages, you can perform several operations on top of the different packages:

  • dev: build the site and serve it locally with live reload, rebuilding on every change.
  • build: builds the documentation site once.
  • clean: removes the local build output.
  • check-links: checks the built site for broken links.
  • git:pre-push: builds the site and runs check-links, used as this repo's pre-push hook.

All this operations can be performed launching the following command on the /docs folder:

npm run <operation>

Documentation Flow

For start:

  1. Install the documentation dependencies.
  2. Start the documentation site locally (npm run dev).

To make a change and test it:

  1. Make a change on an AsciiDoc file and save it.
  2. Check the changes on the live local site.

As you can see to test you can repeat steps 1-2 as many times as you want.

Documentation Release Checklist

Complete this checklist for every release, not for every individual change. You may still update it incrementally as changes are made to keep track of what is pending for the next release.

  1. Identify the upcoming version: the one after the latest released version, matching the release-type/* label of the PR.
  2. Update code/CHANGELOG.md with the changes included in the release.
  3. If the release includes public API changes, document them in the relevant API reference file under docs.
  4. Create or update the release notes page at docs/src/modules/main/pages/release-notes/<version>.adoc:
    • If the page is new, add its title, description, release date, and change sections.
    • If the page already exists, add the release changes under the corresponding sections.
  5. Add the new page to the release notes tree in docs/src/modules/main/nav.adoc, keeping versions newest first.
  6. Add an entry for the release at the top of docs/src/modules/main/pages/changelog/index.adoc.

Before Submitting

  • Set the version to release of the docs on the docs/.release-version file.

Helpful Resources

  • Project documentation: Refer to our documentation for more information on the project structure and how to contribute.
  • Issues: Check open issues and look for opportunities to contribute. Make sure to open an issue before starting work on a new feature or fix.

Thank you for your time and contribution! Your work helps to grow and improve this project. If you have any questions, feel free to reach out to us.