Contributing

Git Flow

The repository for @studiometa/ui follows the Git Flow convention, so branches should be prefixed as follow:

• feature/... for new features
• bugfix/... for bug fixes
• release/<version> for releases
• hotfix/<version> for hotfixes

Every merge should be first approved by opening a pull-request against the develop branch for features and bugfixes and against the master branch for releases and hotfixes.

Local development

Clone the project and install the required dependencies. The back-end can be run with ddev which is preconfigured.

git clone https://github.com:studiometa/ui.git
cd ui/

# Install NPM dependencies
npm install
ddev start

# Launch the dev environment
npm run docs:dev

You will then be able to open the documentation development URL localhost:5173/-/ in your browser.

The TypeScript files from the @studiometa/ui packages can be imported in the playground by using a ESM import statement:

import { Figure } from '@studiometa/ui';

While in dev mode, the source TypeScript files will be automatically rebuild on change and made available to the playground at localhost:5173/-/play/index.html.

You can also open the repository in GitPod and start the dev environment there.

Remote development with Gitpod

The repository is also configured to easily run in Gitpod. Just click on the following button to get started:

Adding a component

A component can either be a single TypeScript file, a single Twig template or for more complex features, a combination of both.

💡 Pro tip

Take inspiration from existing components for new implementations.

TypeScript

The default template for a TypeScript component is as follow:

import { Base } from '@studiometa/js-toolkit';
import type { BaseConfig, BaseProps } from '@studiometa/js-toolkit';

export interface NameProps extends BaseProps {}

/**
 * Name class.
 */
export default class Name extends Base<NameProps> {
  static config: BaseConfig = {
    name: 'Name',
  };
}

Once your component is ready, add an export of all its content to the index.ts file of its category. For example, if it is a molecule, edit the packages/ui/index.ts file:

 export * from './Modal/index.js';
+export * from './MyComponent/index.js';
 export * from './Panel/index.js';

Twig

All Twig templates should at least expose an attr variable that can be used to configure the attributes of the HTML root element of the template. To facilitate this pattern, we use functions added by our studiometa/twig-toolkit.

{% set default_attributes = { class: 'block' } %}
{% set required_attributes = { data_component: 'MyComponent' } %}

{% set attributes = merge_html_attributes(
  attr ?? null,
  default_attributes,
  required_attributes,
) %}

<div {{ html_attributes(attribute) }}>
  ...
</div>

Publishing a new version

To publis a new version, create a release branch:

git flow release start 0.2.41
# or without gitflow
git checkout develop
git pull origin develop
git checkout -b release/0.2.41

In this release branch, update the version number of all packages with the following command:

npm version 0.2.41 -ws --include-workspace-root

Edit the CHANGELOG.md file to add the version number and the date of the release:

 ## [Unreleased]

+## [v0.2.41](https://github.com/studiometa/ui/compare/0.2.40..0.2.41) (2024-02-13)
+

Open a pull-request to validate the changes and make sure all tests are passing. Once the PR is approved, merge the release:

git flow release finish
# or with git
git checkout master
git pull origin master
git merge release/0.2.41 --no-ff
git tag 0.2.41 --message 'v0.2.41'
git checkout develop
git merge 0.2.41 --no-ff

And push all the changes to GitHub:

git push origin develop
git push origin master
git push origing --tags

GitHub actions will create a release on GitHub and publish the @studiometa/ui packages to NPM. The Packagist package will be updated with the latest tag as well.