diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e0e76b2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,195 @@ +# VAR-Meta UI Contributing Guide + +Hello!, I am very excited that you are interested in contributing with Var-Meta UI. However, before submitting your contribution, be sure to take a moment and read the following guidelines. + +- [Code of Conduct](https://github.com/VAR-META-Tech/Var-Meta-UI/blob/main/CODE_OF_CONDUCT.md) +- [Extraction request guidelines](#pull-request-guidelines) +- [Development Setup](#development-setup) +- [Tests](#tests) +- [Visual Changes](#visual-changes) +- [Documentation](#documentation) +- [Breaking Changes](#breaking-changes) + +### Tooling + +- [PNPM](https://pnpm.io/) to manage packages and dependencies +- [Tsup](https://tsup.egoist.dev/) to bundle packages +- [Storybook](https://storybook.js.org/) for rapid UI component development and + testing +- [Testing Library](https://testing-library.com/) for testing components and + hooks +- [Changeset](https://github.com/atlassian/changesets) for changes + documentation, changelog generation, and release management. + +### Commit Convention + +Before you create a Pull Request, please check whether your commits comply with +the commit conventions used in this repository. + +When you create a commit we kindly ask you to follow the convention +`category(scope or module): message` in your commit message while using one of +the following categories: + +- `feat / feature`: all changes that introduce completely new code or new + features +- `fix`: changes that fix a bug (ideally you will additionally reference an + issue if present) +- `refactor`: any code related change that is not a fix nor a feature +- `docs`: changing existing or creating new documentation (i.e. README, docs for + usage of a lib or cli usage) +- `build`: all changes regarding the build of the software, changes to + dependencies or the addition of new dependencies +- `test`: all changes regarding tests (adding new tests or changing existing + ones) +- `ci`: all changes regarding the configuration of continuous integration (i.e. + github actions, ci system) +- `chore`: all changes to the repository that do not fit into any of the above + categories + + e.g. `feat(components): add new prop to the avatar component` + +If you are interested in the detailed specification you can visit +https://www.conventionalcommits.org/ or check out the +[Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). + +## Pull Request Guidelines + +- The `main` branch is basically a snapshot of the latest production version. All development must be done in dedicated branches and will be merged to `canary` branch. +- Make sure that Github Actions are green +- It is good to have multiple small commits while working on the PR. We'll let GitHub squash it automatically before the merge. +- If you add a new feature: + - Add the test case that accompanies it. + - Provide a compelling reason to add this feature. Ideally, I would first open a suggestion topic and green it before working on it. +- If you correct an error: + - If you are solving a special problem, add (fix #xxxx [, # xxx]) (# xxxx is the problem identification) in your PR title for a better launch record, for example update entities encoding / decoding (fix # 3899). + - Provide a detailed description of the error in the PR. Favorite live demo. + - Add the appropriate test coverage, if applicable. + +### Steps to PR + +1. Fork of the var-meta-ui repository and clone your fork + +2. Create a new branch out of the `canary` branch. We follow the convention + `[type/scope]`. For example `fix/dropdown-hook` or `docs/menu-typo`. `type` + can be either `docs`, `fix`, `feat`, `build`, or any other conventional + commit type. `scope` is just a short id that describes the scope of work. + +3. Make and commit your changes following the + [commit convention](https://github.com/VAR-META-Tech/Var-Meta-UI/blob/main/CONTRIBUTING.md#commit-convention). + As you canary, you can run `pnpm build --filter=` and + `pnpm test packages//` e.g. `pnpm build --filter=avatar & pnpm test packages/components/avatar` to make sure everything works as expected. + + > To know more about the `--filter` option, please check the turborepo [docs](https://turborepo.org/docs/core-concepts/filtering). + +4. Run `pnpm changeset` to create a detailed description of your changes. This + will be used to generate a changelog when we publish an update. + [Learn more about Changeset](https://github.com/atlassian/changesets/tree/master/packages/cli). + Please note that you might have to run `git fetch origin main:master` (where + origin will be your fork on GitHub) before `pnpm changeset` works. +5. Also, if you provide `jsx` snippets to the changeset, please turn off the + live preview by doing the following at the beginning of the snippet: + ` ```jsx live=false` + +> If you made minor changes like CI config, prettier, etc, you can run +> `pnpm changeset add --empty` to generate an empty changeset file to document +> your changes. + +## Development Setup + +After cloning the repository, execute the following commands in the root folder: + +1. Install dependencies + +```bash +pnpm i --hoist + +#or + +pnpm install --hoist +``` + +We use [Turbo Repo](https://turborepo.org/) for the project management. + +2. If you will be working on the components source code, you can use the following command to start the webpack dev server: + +```bash +## Start the dev server +pnpm dev + +``` + +Remember that these commands must be executed in the root folder of the project. + +3. Create a branch for your feature or fix: + +```bash +# Move into a new branch for your feature +git checkout -b feat/thing +``` + +```bash +# Move into a new branch for your fix +git checkout -b fix/something +``` + +4. If your code passes all the tests, then push your feature/fix branch: + +All commits that fix bugs or add features need a test. +You can run the nest command for component specific tests. + +```bash +# Test current code + +pnpm test + +# or + +npm run test +``` + +```bash +# Test isolated component code + +pnpm test button + +# or + +npm run test button + +``` + +5. Be sure the package builds. + +```bash +# Build current code + +pnpm build + +# or + +npm run build +``` + +> Note: ensure your version of Node is 16 or higher to run scripts + +6. Send your pull request: + +- Send your pull request to the `dev` branch +- Your pull request will be reviewed by the maintainers and the maintainers will decide if it is accepted or not +- Once the pull request is accepted, the maintainers will merge it to the `dev` branch + +## Visual Changes + +When making a visual change, please provide screenshots +and/or screencasts of the proposed change. This will help us to understand the +desired change easier. + +Until VAR-META-UI has a stable release new components will be created only for the core team. + +## Documentation + +Updating ... + +## Breaking changes + +Breaking changes should be accompanied with deprecations of removed functionality. The deprecated APIs themselves should not be removed until the minor release after that. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..fbf5770 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 VAR META + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/ui/README.md b/packages/ui/README.md index 7453ee2..bfdeee1 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -4,6 +4,10 @@ Here you can find the guidelines, components APIs and examples to help you build your next project with VAR-UI. +## Documentation + +Visit [https://ui.var-meta.com](https://ui.var-meta.com) to view the full documentation. + ## Install The UI came with different packages, namely `@var-meta/icons` and `@var-meta/ui`.