Skip to content

Latest commit

 

History

History
162 lines (129 loc) · 11.5 KB

CONTRIBUTING.md

File metadata and controls

162 lines (129 loc) · 11.5 KB

Contributing

To develop components, after cloning the repo, make sure you install the dependencies:

npm i

Run storybook by running

npm start

Run next.js if needed by running

npm run next:dev

Now you can create components and its related stories.

Available commands

  • prestart - The command that runs before the start script
  • start - Starts the development environment
  • next:dev - Runs next.js' development environment
  • next:build - Builds next.js' development environment
  • next:start - Runs next.js' production environment (but you need to build first)
  • prettier - Runs prettier CLI to clean up files
  • lints - Runs eslint CLI to check for declared rules
  • lints:fix - Runs eslint CLI to check for declared rules and tries to automatically fix issues if possible
  • type-check - Runs the typescript type checked to check if there is any type error
  • check-commit - Runs all required checks to create a commit
  • storybook - Runs storybook
  • build-storybook - Builds a static html version of storybook so it can be deployed
  • rollup:build - Builds the project and outputs the dist files to generate a npm package
  • rollup:watch - Watch for file changes and builds the project if a file has been changed
  • prepare - The command that runs automatically by npm, before a npm package upload

Architecture

The architecture is how we setup the repository structure:

** This project must not have any element/template/layout components because we should only have pure, ui components, with no business logic, only the logic for the component to function

Contributing to the code

  • You'll need github cli, there are different ways of doing the same thing but I think it's just easier to make the release with the github cli: https://cli.github.com/. Note that it is not the same thing as the git cli

It is recommended that you read and understand all of these before starting, they are tailwind's core concepts:

Pushing your changes

  1. Split the commits in small chunks of logic. For example, a single component per commit, or a single fix per commit. If you made all the changes before the commit. You can split those using the staging strategy, and then only committing the staged files.

  2. Make your changes in a branch.

    • Make sure to update it with master first. You can run the command: git checkout {BRANCH_NAME} && git fetch && git merge origin/master && git push before working in a branch that might not be up to date. (Remember to update {BRANCH_NAME} to your branch name)

  3. Don't commit yet. It is nice to update the CHANGELOG.md file in the same commit of your current change.

  4. Change the CHANGELOG.md file, under [Unreleased], and add a simple text explaining the change for the current commit. Also make sure to put it in the correct category, for example Fixes, or Changes, or Added. Do this for each commit separately

  5. Now you can push the change with both the code + CHANGELOG.md

Bumping the version

  1. This is done in your branch and not master
  2. After you pushed all the changes and decided you're done. Raise the version in package.json accordingly. Following the semver strategy.
  3. Don't push yet.
  4. Update the CHANGELOG.md file by adding the new version title right before the previous version but under [Unreleased], date it today, copy the contents of [Unreleased], remove the unused/empty headers, and add back(or delete the duplicated content in) the [Unreleased] template. (There's a commented version in the beginning of the file that you can copy/paste if needed).
  5. Now you commit/push it with the message: build: bumping version: {VERSION_NUMBER}(Remember to update {VERSION_NUMBER} to the current version, and to remove the square brackets {})
  6. This way you have a separate commit only for the changes, which could be 1 or more or whatever. And a separate commit only for the version bump.
  7. Now you can push it.

Generating the npm package

  1. Make PR to master
    • On your branch, do a gh pr create -B master command or just create it in the browser
    • You can name the PR the name of the current version for example: 1.1.9
  2. Read the instructions in the PR message, check the boxes accordingly
  3. Ask for a code review.

Making a release

  1. After having your branch merged into master
  2. Create a RELEASE.md file in the project root if you don't have one.
  3. Copy only the latest version content from CHANGELOG.md and paste in your RELEASE.md, then save. So it has the contents for the current but not other versions, unlike the changelog file.
  4. Go to this page and find the latest merge commit, which should be the merge that just happened: https://github.com/perimetre/ui/commits/master
  5. Copy the commit SHA code for that commit, the SHA code is the little number/string in the commit's right side.
    • You can click the clipboard icon which will copy the entire code
  6. Now you'll need to checkout to master, pull, generate the tag, push the tag and make a release for that tag:
    • You can use this chain command: 
      git add . && git stash && git checkout master && git pull && git tag -a v{VERSION} {COMMIT_SHA} -m "v{VERSION}" && git push origin v{VERSION} && gh release create v{VERSION} -F RELEASE.md
    • Note the {VERSION} and {COMMIT_SHA}. You need to replace it with the version number, example 1.1.9, the commit sha, and remove the brackets {}.
    • Note that if you have uncommited changes, they'll get stashed.
    • Example: 
      git add . && git stash && git checkout master && git pull && git tag -a v1.1.7 a4e0d64 -m "v1.1.7" && git push origin v1.1.7 && gh release create v1.1.7 -F RELEASE.md
  7. The github action will start right when the tag is pushed to master, and a new package will be generated. After it's finished you can install the new version.

Adding more components/css classes

  1. Create a folder in ./src/components/UI with your component name
  2. Create either the index.tsx or index.css file, or both depending in your case.
  3. If it's a CSS component, make sure to import it in ./src/components/index.css, like it's being done with other components.
  4. If it's a Base CSS style, make sure to import it in ./src/components/base.css, like it's being done with other base styles.
  5. If it's a React component, make sure to export it in ./src/components/index.tsx, like it's being done with other components.
  6. Make sure to wrap your css with the @layer directive, like it's being done with other components.
  7. Make sure to append pui- as a prefix to all css classes, css variables, tailwind variables/values, mostly everything that is not related to react, like it's being done with other components.
  8. Make sure to add as much (reasonable) comments as possible
  9. Make sure to create a compelling story in storybook for your component, providing the variants, default values and available options for different properties of your component. Check out other stories for components with css only and also stories for react components, and do something similar.
  10. Look at other components, simple and complex ones, for example: WYSIWYGInput, TextInput, Button, Drawer, Badge, Link, Modal, FontFamily. To make sure you're following the same pattern

Adding more icons

  1. Run the command npm run next:dev
  2. Go to http://localhost:3000/optimize
  3. In your svg string, change any fill attributes that sets a color, to fill="currentColor". (Only change ones that sets a color. Other fill attributes like fill="none" can remain intact)
  4. In your svg string, make sure to not include any React {} tags, you have to convert those to html tags, you must paste a plain html svg, not a react component/svg.
  5. Then, paste your SVG string in the first input
  6. Preview your svg in the top section, your svg should be visible and working in all modes: Original, Optimized and CSS
  7. If your svg is broken:
    • Check if there are any <defs> tags in your svg, first. Then move them to their correlated <use> tags.
    • If it's still broken, uncheck "Remove color attributes" (Uncheck only if it's broken)
  8. There shouldn't have any red text under the preview icons. If there is, follow the instructions of the text to fix the issue before continuing
  9. Copy an existing icon file in ./src/components/icons
  10. Update the icon name everywhere in the file, and the filename itself.
  11. Update the svg icon in the file you just copied, replacing it with what's in "Optimized SVG" in http://localhost:3000/optimize
  12. Add the {...props} statement before the end of the first svg tag (look at how it's done in other icons)
  13. Make sure to add a class name according to the icon type. fill-current or stroke-current (look at how it's done in other icons). To know which one you need to add. You will need to test the icon using the icon story in storybook.
  14. Update the URL icon version in the file you just copied, replacing it with what's in "uri() version" in http://localhost:3000/optimize
  15. Insert a new import in ./src/components/icons/index.tsx that references your new icon
  16. Go to ./src/components/icons/index.css, and copy the latest icon class, at the bottom
  17. Paste your copied icon class, rename the last part of the class name, which contains the icon name, to your icon name, following the other classes pattern
  18. Update the url(' replacing it with what's in "uri() version".
  19. Make sure --pui-absolute-icon-size, has the correct icon size. You can look at the svg tag width/height/viewbox attribute to get the correct size
  20. Run the command npm run dev
  21. Go to the icons story
  22. Select your icon in the dropdown
  23. Make sure your icon works with any color and any size by changing the controls and looking at the output, using the story

Resources