readme.md

# HUDS developer guide, basic workflow

## Stencil

1. Have discussions with designers, agree on basic functionality
2. run `yarn generate` and start development
3. Extract useful helper components, such as `<hy-row> <hy-column>`
4. Review the design with designer and PO or a colleague
5. Check with basic accessibility tools (TBD which tools?!?)
6. Write component documentation. At least it should
   1. Have a short introduction
   2. List all states the component can be in.
   3. List all variants the component can have
   4. Include code examples
7. Write unit tests where it makes sense. We use jest and puppeteer.
8. Run `bash bumpversion.sh` to run tests and bump the version number.
9. Do a final commit with all the build artefacts included.
10. Make a merge request -> pass the code review -> celebrate!

## Writing documentation in Vuepress

You should install the documentation project from https://version.helsinki.fi/julkiset-sivut/design-system.

To run it with your version of the design system, follow these steps:

1. Clone and install dependencies
2. Run `yarn add https://version.helsinki.fi/julkiset-sivut/design-system-lib.git#<YOUR-BRANCH>` to update the latest version of the library with the git branch you're currently working on.
3. Add necessary pages inside `.vuepress/config.js`
4. Manually add the Markdown documentation from the repository

## Combined workflow

In case you want to develop and see the component inside documentation right away, you can adapt the following workflow.

Inside the library Make a dynamic link of the library project:

`yarn link`

Inside the Vuepress project

`yarn link <library project name>`

The you need to start both development environments:

Vuepress directory: `yarn docs:dev`

Library directory: `yarn build.watch --target <VUEPRESS FOLDER>`

The second script starts both the stencil watcher in production mode, which builds the actual library on every change. It also concurrently runs a custom watcher script copying markdown files to Vuepress directory.

NOTE: Even when you have the documentation files in Vuepress, you'll need to manually add them to the navigation in docs/.vuepress/config.js

## Running with Docker (WIP)

If you don't want or cannot install node and other dependencies, you can run the development setup locally in a container like this:

First build the container

`docker build -t helsinkifi/huds .`

Then run the image with optional Vuepress location and the npm script you want to run.

NOTE: If you want to use "watchdocs" or "build.watch" scripts, you must include the Vuepress location!

`docker run -v ${PWD}:/usr/src/app -v <YOUR VUEPRESS LOCATION FULL PATH>:/usr/src/app/tempdocuments -p 3333:3333 helsinkifi/huds <NPM SCRIPT>`

For example:

`docker run -v ${PWD}:/usr/src/app -p 3333:3333 helsinkifi/huds build`

TODO:

It's pretty annoying to copy paste long docker commands, so perhaps docker-compose would fit here. Anyone?