Currently this project in a "maintained sunsetting" mode. This means we're starting to remove deprecated/unused components from its codebase with the intent to completely remove as dependency from our products.
But don't worry, if you need to use the old project, there are a couple of "frozen in time" branches that you can use (and potentially even release from, if you need). See "Which version to use?" below.
The current version of this package is the one used for the "managed sunsetting" of the library from our products. As such, in time some components are deprecated and then removed from the repository, and some surgical patches to the code are done when necessary to facilitate the migration to the new UI library (HashiCorp Design System components).
If for any reasons you need to stay on an older version, you can:
- use the package version
0.6.4
to stay "frozen in time" at the moment in which the "maintained sunsetting" phase has started. - use the package version
1.x.x
to stay on a release path that sees only minor patches but not components removal- in this case, if you need to make changes, use the branch
master-version-1.x
and release to NPM from that branch
- in this case, if you need to make changes, use the branch
Old introduction to the project, left for reference:
Pds stands for Product Design System. The original intent was to rename
structure
to Pds because the developer at the time thought it was more clear. Unfortunately, that renaming never happened so there are two names. This is a mono repo with the idea that the Ember, React, etc projects scattered around Hashi could all eventually rely on a single source for design components. Currently there is onlypds-ember
.
To contribute to the pds-ember
package (currently the only package in this mono repo) please see the Contributing guide for details.
yarn workspace @hashicorp/pds-ember version patch
to bump the version by a "patch" increment (see Semantic Versioning)- Git add the yml file and the version update generated by the command.
- Create a new PR for this and get it approved and merged into main.
- Checkout main branch, pull down the new changes.
- Use
git tag [PACKAGE-NAME]-[VERSION]
e.g.git tag pds-ember-2.0.2
git push --tags
- Go to https://github.com/hashicorp/structure/tags
- Select the tag just pushed in Git and from the submenu select "Create release"
- Use
pds-ember-[VERSION]
as release title - Click the "Generate release notes" button (the
description
will be automatically filled by GitHub)
- Make sure your NPM account has been added to the Hashi group (check with IT)
yarn workspace @hashicorp/pds-ember npm publish
Troubleshooting: If you get authentication errors from npm publish, you might have to do a login via workspace, before calling npm publish
:
yarn workspace @hashicorp/pds-ember npm login
In this case you will need to do a two-factors authentication (2FA) on NPM before the login (via npmjs website)
- In the repo consuming update
package.json
to use the new version of the structure package. If it's in another mono repo with multiple packages, replace the version in each package to the new version (find/replace). - Run βyarnβ on base level of the repo to update all of them.
- Add package changes and yarn lock file.
- Open a pr!
The current version of this package is the one used for the "managed sunsetting" of the library from our products. As such, in time some components are deprecated and then removed from the repository, and some surgical patches to the code are done when necessary to facilitate the migration to the new UI library (HashiCorp Design System components).
If for any reasons you need to stay on an older version, you can:
- use the package version
0.6.4
to stay "frozen in time" at the moment in which the "maintained sunsetting" phase has started. - use the package version
1.x.x
to stay on a release path that sees only minor patches but not components removal- in this case, if you need to make changes, use the branch
master-version-1.x
and release to NPM from that branch
- in this case, if you need to make changes, use the branch
To remove a component (eg. Pds::Xyz
) from the Structure repository the steps to follow are more or less these.
- first of all make sure it's not used anymore:
- search for
<Pds::Xyz
in the Cloud UI codebase (you should expect zero occurrencies)- if you find a limited number of occurrencies (eg. 1-3) consider if it would make sense to migrate the
Pds::Xyz
code and logic directly where it's consumed in Cloud UI and remove the component from Structure
- if you find a limited number of occurrencies (eg. 1-3) consider if it would make sense to migrate the
- search for
<Pds::Xyz
in the Structure codebase (you should expect zero occurrencies as well)- if you find a limited number of occurrencies (eg. 1-3) consider if it would make sense to embed the
Pds::Xyz
code and logic directly where it's consumed in Structure and don't expose it as component
- if you find a limited number of occurrencies (eg. 1-3) consider if it would make sense to embed the
- search for
- delete all the code related to the
Pds::Xyz
component, once you have decided it's OK to remove the component:- you can search for all the files related to the
Pds::Xyz
component as you would normally do in your IDE/editor - or you can use this PR to have a general idea of what needs to be removed: #118
- in both cases these are more or less the steps to follow:
- remove all the files in
packages/pds-ember/addon/components/pds/xyz
- remove all the files in
packages/pds-ember/app/components/pds/xyz
- remove all the files in
packages/pds-ember/app/styles/pds/components/xyz
- remember to remove the imports from
packages/pds-ember/app/styles/pds/components/index.scss
- check if other components are importing any of the Sass definitions for
xyz
via@use
, in which case copy the definitions where they're used or abstract them somewhere
- remember to remove the imports from
- remove all the files in
packages/pds-ember/tests/integration/components/xyz
- now search the entire codebase for
xyz
(case insensitive) and look what needs to be done for every remaining occurrence (it will depend case by case) - add a markdown file
packages/pds-ember/docs/deprecated/pds-xyz.stories.mdx
explaining what to do with this component (use the files in the same folder as guidance of what to write)- run
yarn build-storybook
and thenyarn storybook
to check that the page just created works correctly (and there are no crashes in the app because of missing components or references)
- run
- remove all the files in
- you can search for all the files related to the
- test the changes in Cloud UI:
- go in the root of the https://github.com/hashicorp/cloud-ui/
- pull the latest version of the
main
branch (or the branch you're working on, if this work in Structure is related to it) - in the project root:
- run
yarn
to install all the needed dependencies cd
innode_modules/@hashicorp
- remove the
pds-ember
folder - create a symlink between your local version of Structure (the one that you're working on, with the component(s) removed) and the one consumed by Cloud UI using the command
ln -s [path-to-your-local-structure-project-folder]/packages/pds-ember [path-to-your-local-cloud-ui-project-folder]/node_modules/@hashicorp/.
- don't forget, once you've finished testing, to remove the symlink and re-run
yarn
to install properly all the dependencies
- don't forget, once you've finished testing, to remove the symlink and re-run
- run
- run the HCP/Cloud UI application and check that everything is OK
- notice: while doing some tests we noticed that the header of the application is not rendered correctly, for some reasons; but it's OK, the app works anyway, maybe some issues with the fact that the package is actually a symlink
- open a new PR to get the changes approved
- once you are OK with the changes and you have pushed them in your development branch, open a new PR in this repo (if you want you can use this PR as model: #118)
- when the changes are approved and merged, follow the instructions above on how to release a new version of Structure
- and finally, once the package is available on NPM, you can open a PR in Cloud UI to bump the version of the Structure
@hashicorp/pds-ember
dependency