diff --git a/.storybook/preview.ts b/.storybook/preview.ts index 48f12831e..525a63f85 100644 --- a/.storybook/preview.ts +++ b/.storybook/preview.ts @@ -7,12 +7,7 @@ const preview: Preview = { storySort: { order: [ 'About', - ['Introduction', 'Contributing', 'Changelog', 'FAQ'], - 'Components', - 'Foundations', - ['Colors', 'Typography', 'Icons', 'Errors', 'Loading'], - 'Candidate Components', - 'Design Templates', + ['Introduction', 'Changelog', 'FAQ'], 'Component Process', [ 'Introduction', @@ -22,6 +17,13 @@ const preview: Preview = { ['Introducing new ones', 'Using existing ones', 'Promoting to a component'], 'Design Templates', ], + 'Components', + 'Foundations', + ['Colors', 'Typography', 'Icons', 'Errors', 'Loading'], + 'Candidate Components', + 'Design Templates', + 'Contributing', + ['Introduction', 'Commits', 'Testing in the platforms', 'Release Process', 'Maintainers'], ], }, }, diff --git a/docs/About/Contributing.mdx b/docs/About/Contributing.mdx deleted file mode 100644 index 3b37ca50e..000000000 --- a/docs/About/Contributing.mdx +++ /dev/null @@ -1,5 +0,0 @@ -import { Markdown } from "@storybook/blocks" - -import contributing from '../../CONTRIBUTING.md?raw' - -{contributing} \ No newline at end of file diff --git a/docs/About/FAQ.mdx b/docs/About/FAQ.mdx index 82541bb6a..e1e56fa86 100644 --- a/docs/About/FAQ.mdx +++ b/docs/About/FAQ.mdx @@ -1,3 +1,6 @@ # FAQ -### What should I do if I can't implement my needs using Antd \ No newline at end of file +### What should I do if I can't implement my design specs using Antd atoms? + +Please ask questions about it in the #aquarium channel. Ideally have a branch with your work in progress and some Storybook +stories so that we can see what you're trying to do. \ No newline at end of file diff --git a/docs/About/Introduction.mdx b/docs/About/Introduction.mdx index 84c4b0571..ef0490960 100644 --- a/docs/About/Introduction.mdx +++ b/docs/About/Introduction.mdx @@ -1,6 +1,6 @@ # Introduction -Hi! +This is where all component related documentation will live at mParticle. ## How to read this @@ -10,10 +10,10 @@ TBD | Term | Meaning | | -------- | ------- | -| Component Candidate | Explanation | -| Template | Explanation | -| Eames | Explanation | -| Aquarium | Explanation | -| Antd | Explanation | +| Component Candidate | TBD | +| Template | TBD | +| Eames | TBD | +| Aquarium | TBD | +| Antd | TBD | --- \ No newline at end of file diff --git a/docs/Component Process/Introduction.mdx b/docs/Component Process/Introduction.mdx index f6ecaa676..859526c36 100644 --- a/docs/Component Process/Introduction.mdx +++ b/docs/Component Process/Introduction.mdx @@ -1 +1,3 @@ -# Introduction \ No newline at end of file +# Introduction + +TBD \ No newline at end of file diff --git a/docs/Contributing/Commits.mdx b/docs/Contributing/Commits.mdx new file mode 100644 index 000000000..adbc43c95 --- /dev/null +++ b/docs/Contributing/Commits.mdx @@ -0,0 +1,41 @@ +# Commits + +## Commit conventions and PR titles + +- We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to help automating the release process. Both PR titles and commit messages should follow this convention. +- [This repo is commitizen friendly](https://github.com/commitizen/cz-cli?tab=readme-ov-file#using-the-command-line-tool) so we can use `git cz` to commit changes. +`npx cz` is also available if you don't have commitizen installed globally. +- We also have a [commitlint](https://commitlint.js.org/) setup to enforce the commit message format. + +The standard format for commit messages is as follows: + +``` +[optional scope]: + +[optional body] + +[optional footer] +``` + +The following lists the different `types` allowed in the commit message: + +- feat: A new feature (automatic minor release) +- fix: A bug fix (automatic patch release) +- docs: Documentation only changes +- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- refactor: A code change that neither fixes a bug nor adds a feature +- perf: A code change that improves performance +- test: Adding missing or correcting existing tests +- chore: Changes that don't modify src or test files, such as automatic documentation generation, or building latest assets +- ci: Changes to CI configuration files/scripts +- revert: Revert commit +- build: Changes that affect the build system or other dependencies + +In the footer, if there is a breaking change, start your footer with `BREAKING CHANGE:` followed by a description. + +## Editor configuration + +- **Prettier**: For configuring your editor to play nicely with Prettier, take a look at the [Editors doc page](https://prettier.io/docs/en/editors). +- Also, if you're using VSCode you might want to set prettier as the default formatter and also turn on "Format on Save" option. +- **ESLint**: Check [Integrations doc page](https://eslint.org/docs/latest/use/integrations) +- **Stylelint**: Check [Editor integrations doc page](https://stylelint.io/awesome-stylelint/#editor-integrations) \ No newline at end of file diff --git a/docs/Contributing/Introduction.mdx b/docs/Contributing/Introduction.mdx new file mode 100644 index 000000000..2c3813fac --- /dev/null +++ b/docs/Contributing/Introduction.mdx @@ -0,0 +1,4 @@ +# Introduction + +Thanks for the interest in contributing to the Aquarium! Being a component library requires a different approach to development and testing. +This document will guide you through the process of contributing to the Aquarium. \ No newline at end of file diff --git a/docs/Contributing/Maintainers.mdx b/docs/Contributing/Maintainers.mdx new file mode 100644 index 000000000..4d1ea4fe1 --- /dev/null +++ b/docs/Contributing/Maintainers.mdx @@ -0,0 +1,3 @@ +# Maintainers + +TBD \ No newline at end of file diff --git a/docs/Contributing/Release Process.mdx b/docs/Contributing/Release Process.mdx new file mode 100644 index 000000000..2f015f2aa --- /dev/null +++ b/docs/Contributing/Release Process.mdx @@ -0,0 +1,32 @@ +# Release Process + +We use [semantic-release](https://github.com/semantic-release/semantic-release) to automate the versioning and publishing +of the mParticle Aquarium component library. Everything is handled by semantic-release, including determining the next version number, +generating the release notes, and publishing to npm. You can use the Github Release Aquarium action from the `main` branch to release from it. + +> [!IMPORTANT] +> Before releasing a version from main, send a message in the #aquarium Slack channel to align it and sync on other changes that can/should be included in the release. + +## Contributing with the release process + +To make changes to the release process, you can use the `--dry-run` from semantic-release flag to test the release +process without actually publishing a new version. + +You will need two environment variables to run the release process locally: + +- NPM_TOKEN: You can create a personal npm account and use a personal token. +Since we are using `--dry-run` it won't try to publish anything so having a valid read-only npm token works. + +- GITHUB_TOKEN: Create a [github personal access token (classic)](https://github.com/settings/tokens) +and give it access to the mParticle organization via "Configure SSO" button. + +After settings both variables locally, run the following locally: + +``` +npx semantic-release --dry-run +``` + +## Additional readings: + +- [Semantic Release Workflow Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/workflow-configuration.md#workflow-configuration) +- [Understanding npm distribution channels](https://docs.npmjs.com/cli/v8/commands/npm-dist-tag#purpose) \ No newline at end of file diff --git a/docs/Contributing/Testing in the platforms.mdx b/docs/Contributing/Testing in the platforms.mdx new file mode 100644 index 000000000..01b2f6bb7 --- /dev/null +++ b/docs/Contributing/Testing in the platforms.mdx @@ -0,0 +1,30 @@ +# Testing in the platforms + +## Testing in the CDP + +In order to test your changes, you will need to link the local version of the library. To do this, run the following commands: + +- Make sure to have the library built by running `npx vite build`. The linked version will use the build files from _dist/_ folder. +- Make sure the `resolve.symlinks` property in you webpack config is set to `false` +- `yarn link` in the root of the library +- `yarn link @mparticle/aquarium` in the root of Nancy +- Make sure your _/node_modules/@mparticle/aquarium_ folder contains all of the Aquarium code + +## Testing in Analytics + +TODO + +## Testing by installing from a branch + +Another way to test your changes is by installing the library from a branch. To do this, we need to push the _dist/_ folder to the remote +and install it directly from there with the following command: + +``` +yarn add https://github.com/mParticle/aquarium# +``` + +## Testing by releasing an ad-hoc version + +To test ad-hoc versions of the Aquarium we use `feat/`, `fix/` or `chore/` branchs on Github and their corresponding distribution channels on npm. +This allows us to release specific versions for testing specific features and install them on the platforms. To release it, +just run the Github Action from the the branch you want to release. \ No newline at end of file