DiPlanung Style

This repository contains the DiPlanung project's style guide NPM package. This enables consistent design and the easy reuse of style rules across all front-end applications by providing shared design resources, such as Vue components, icons and fonts. It will also promote consistent user interfaces and accelerate development by providing centralised design resources.

• Requirements
• Installation
• Documentation & Storybook
• Development Guide
• CI/CD
• Branching and Releases
• Authors and acknowledgment
• License

Requirements

• nodejs >= 22.16.0
• npm >= 10.9

Installation

To install the node module:

npm install --save diplanung-style

Documentation with Storybook

The diplanung-style project includes its own Storybook - a tool that allows teams to design, build, and organize UI components. Stories are used to display the different forms and statuses of a component.

The hosted Storybook can be found here: https://style.develop.diplanung.de/

• https://storybook.js.org/
• https://github.com/storybookjs/storybook

Markdown (MDX)

MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast 🚀.

• https://mdxjs.com/
• https://www.gatsbyjs.com/docs/reference/markdown-syntax/

Development Guide

The frontend is compiled by npm scripts. These can be found in the package.json under "scripts". The terminal commands are executed in the root folder of the project.

• Install all dependencies npm install
• Start the dev environment npm run storybook
• Open Storybook: http://localhost:6006

The node_modules folder should not be added to git!

Azure NPM Registry

To install the dependencies a ADO_NPM_AUTH_TOKEN is needed (see Setup und Konfiguration NPM für ADO).

Conventional Commits

The version number and changelog of a release is auto-generated by the respective commit messages. To work properly, commit messages must follow the conventional commit specification.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

| Type | Description | Changelog section | | -------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | feat | for a new feature for the user, not a new feature for build script. Such commit will trigger a release bumping a MINOR version. | Features | | fix | for a bug fix for the user, not a fix to a build script. Such commit will trigger a release bumping a PATCH version. | Bug Fixes | | perf | for performance improvements. Such commit will trigger a release bumping a PATCH version. | | docs | for changes to the documentation. | | style | for formatting changes, missing semicolons, etc. | | refactor | for refactoring production code, e.g. renaming a variable. | | test | for adding missing tests, refactoring tests; no production code change. | | build | for updating build configuration, development tools or other changes irrelevant to the user. | | chore | for other changes that don't modify src or test files | | ci | for changes to the CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) | | revert | for reverts of a previous commit |

More infos:

• https://www.conventionalcommits.org/en/v1.0.0/
• http://karma-runner.github.io/6.3/dev/git-commit-msg.html
• https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md#commiturlformat-string

Create a Component

If you want to create a new Vue.js component, please use the following script. It adds all the necessary files and exports, so you don't need to create them manually.

npm run gen:component

Tag your component

All component changes should be mark with a corresponding tag. Remove the tag with the next major version update.

const meta: Meta<typeof DpsComponentXY> = {
  title: "Components/DpsComponentXY",
  tags: ["new"],
  ...
}

These are the defined tags:

| Type | Description | | ------------ | --------------------------------------------------------------------------------- | --- | | new | for a new component | | experimental | for an experimental component that is not yet recommended to be used i production | | updated | for a component that included breaking changes in the last release | | deprecated | for a component that will be deprecated in a future release | |

More tags can be configured in .storybook/manager.ts

Local Development

If you want to test your changes, you can load the diplanung-style package from the file system.

MyProjects/
├── diplancockpit.efa/ <-- your project
├── diplanung-style/
├── ...
└── ...

In your package.json change the dependency to:

{
  "dependencies": {
    "diplanung-style": "file:../diplanung-style"
  }
}

Since the package exports the compiled bundle from the dist/ folder, you need to create a new build. Otherwise your changes won't be visible in your project.

npm run build

CI/CD

azure-pipelines.yml uses the standard pipeline to create and publish a Docker image containing the Storybook and builds the NPM package and pushes it to the ADO registry.

Branching and Releases

For a complete documentation of our project workflow including the Branching Strategy and our Release Process please refer to our Wiki Documenation

Authors and acknowledgment

]init[ AG für digitale Kommunikation, Berlin

License

MIT