diff --git a/doc/component-lifecycle.md b/doc/component-lifecycle.md index 45769017242828466b88efed73d40ad877451f96..d345353789c0fe28bf9d725a6da066832e56855d 100644 --- a/doc/component-lifecycle.md +++ b/doc/component-lifecycle.md @@ -1,9 +1,13 @@ # Building and styling a component -A component follows the [lifecycle defined in the +**Note**: If you are building or styling a component not documented in +[https://design.gitlab.com](https://design.gitlab.com), feel free to skip this diagram and follow +the [guidelines to adding a new component to GitLab UI](contributing/adding_components.md). + +A component follows the [lifecycle defined in the Pajamas repository](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/blob/master/doc/component-lifecycle.md). -The following diagram outlines the steps needed to complete the build and style +The following diagram outlines the steps needed to complete the build and style stages of a component: ```mermaid @@ -11,9 +15,9 @@ graph TD; A[Start] -->B[Review issue] B--> C[Review usage guidelines and specs in Pajamas] C--> D{New or existing component?} -D--> |New| E[Create Vue component in gitlab-ui] +D--> |New| E[Create Vue component in GitLab UI] E--> F[Create demos as described in Pajamas docs] -F--> G[Style component in gitlab-ui] +F--> G[Style component in GitLab UI] G-->H[Review by Product Designer] H-->|Changes requested| G H-->|Approved| R[Remove 'Component does not conform' warning banner from Vue tab in Pajamas] @@ -32,30 +36,31 @@ Q-->H ## Updating GitLab Packages -When a change to gitlab-ui is made, it will not be reflected in -[Pajamas](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com) until -the package is updated. We are utilizing [Renovate GitLab Bot](https://gitlab.com/leipert-projects/renovate-gitlab-bot) +When a change to GitLab UI is made, it will not be reflected in +[Pajamas](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com) until +the package is updated. We are using [Renovate GitLab Bot](https://gitlab.com/leipert-projects/renovate-gitlab-bot) to automate this process. -Once an MR is created to bump the version, it will need to be merged by a maintainer. +Once an MR is created to bump the version, it will need to be merged by a maintainer. At this time, the changes should be viewable on the Pajamas site. # Component status -Not all components within gitlab-ui are utilized within the GitLab product at this -time. However, some components have been implemented and others have been migrated -from [GitLab](https://gitlab.com/gitlab-org/gitlab) to [gitlab-ui](https://gitlab.com/gitlab-org/gitlab-ui). -To view which components have been implemented into the product, view our +Not all components within GitLab UI are used in the GitLab product at this +time. However, some components have been implemented and others have been migrated +from [GitLab](https://gitlab.com/gitlab-org/gitlab) to +[GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui). +To view which components have been implemented into the product, view our [component status page](https://design.gitlab.com/components/status) within Pajamas. ## Complex components -There are a few cases where components have been migrated from GitLab to -gitlab-ui but do not yet reflect Pajamas documentation. When a complex component -is difficult to style or update because many features use it, a `New` version of -the component may be created. This allows the team to build and style the component -according to design specs without causing inadvertent side effects to features +There are a few cases where components have been migrated from GitLab to +GitLab UI but do not yet reflect Pajamas documentation. When a complex component +is difficult to style or update because many features use it, a `New` version of +the component may be created. This allows the team to build and style the component +according to design specs without causing inadvertent side effects to features that are already using the migrated Vue component. -For example, see [GlButton](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-button--default) +For example, see [GlButton](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-button--default) vs. [GlNewButton](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-new-button--default) diff --git a/doc/contributing/adding_components.md b/doc/contributing/adding_components.md index f57c33c2c88a0140a082999094ae09ac74d09fde..2aa4e4e653f97aa204fed52cfd7f1cf1a5c25262 100644 --- a/doc/contributing/adding_components.md +++ b/doc/contributing/adding_components.md @@ -1,25 +1,60 @@ # Adding a new component to GitLab UI -1. Decide on a component you'd like to add to `gitlab-ui`. -1. Determine and document the scenarios (different types of implementations, if any) in which this component is used in `gitlab` in an issue in `gitlab-ui`. -1. Select a scenario that is implemented in `gitlab` that you will replace with your component. -1. Run `yarn generate:component` and follow the instructions, or create the files structure manually as follows (where `[component]` is the name of your component): - 1. Create a `[component]/` directory in the relevant `components/` sub-directory. - 1. In this new directory, create the following: - 1. `[component].vue` which is the component itself. - 1. `[component].stories.js` for registering Storybook's stories. - 1. `[component].documentation.js` for registering usage examples. - 1. `[component].md` for documenting the component. - 1. An `examples/` sub-directory where you'll place your examples and an `index.js` file for exposing those examples. -1. Create a merge request (MR) in `gitlab-ui` implementing your new component. - 1. Be sure to name your MR `feat: ` as that is needed for our npm release CI job (don't forget to set the MR to squash commit). - 1. Run the manual CI job (`update_screenshots`) to generate your image snapshots for diffing. -1. Create a MR to `gitlab` to replace the scenario implementation (if any) that you previously selected. - 1. To make this process easier, GitLab UI has a manual CI job called `create_integration_branch` that you can run to automatically create or update an integration branch in GitLab. You would then only need to create a new MR from that branch by following the link in the job's output. -1. Update your `package.json` dependency reference of `@gitlab/ui` to the URL output of the `build_package` CI job in your `gitlab-ui` MR. -1. Run `yarn install` to make sure that the `gitlab-ui` contents are installed. -1. If your new component is used on every page, import to `app/assets/javascripts/commons/gitlab_ui.js` so that your component is globally registered. -1. Once you've verified that your integration MR to `gitlab` is working, assign a maintainer to review both the `gitlab-ui` and `gitlab` MRs. A list of maintainers can be found on the [team](https://about.gitlab.com/team/) page. -1. Maintainer will merge the `gitlab-ui` MR, the `publish` CI job will automatically create a new release on NPM. -1. You (or maintainer) will update your integration MR's `package.json` dependency reference to the newly released `gitlab-ui` version. -1. Maintainer will merge the integration MR. +The following provides guidance for engineers adding new components to GitLab UI. + +## General guidelines + +You should use `yarn generate:component` to begin your component implementation. +This scaffolding tool generates the file structure required by GitLab UI for every component. +It also: + +- Exposes the component in GitLab UI's main entry point file. +- Registers the component’s documentation. +- Imports the component’s stylesheet in GitLab UI’s default CSS bundle. + +You can choose between two templates: _Create Component_ or _Wrap BootstrapVue Component_. + +### Merge Request guidelines + +Create a Merge Request in GitLab UI with your new component code. The Merge Request should follow +these conventions: + +- Name your MR `feat([ComponentName]): Implement [ComponentName] component`. This creates a conventional commit used by the [NPM release CI job](https://gitlab.com/gitlab-org/gitlab-ui/pipelines) to create a new version of the GitLab UI package. +- Check the _Squash commits when merge request is accepted_ option in the Merge Request edit page. + +Run the manual CI job (`update_screenshots`) to generate the baseline snapshots used by the visual +tests. You can find it in last stage of +[GitLab UI CI pipeline](https://gitlab.com/gitlab-org/gitlab-ui/pipelines). +This CI job commits the baseline snapshot images to the merge request branch. + +Update screenshots CI job location + +## Working on a Pajamas-documented component + +If you are adding or updating a component documented in the +[Pajamas design system](https://design.gitlab.com), you should comply with the +[component lifecycle workflow](../component-lifecycle.md). + +## Wrapping a BootstrapVue component + +Use `yarn generate:component` to quickly generate a +[BootstrapVue](https://bootstrap-vue.js.org/) component wrapper in GitLab UI using +the _Wrap BootstrapVue Component_ template. After using the template, follow the same +instructions described in the general guidelines. + +## Testing your new component in GitLab + +You can test your new component in [GitLab](https://gitlab.com/gitlab-org/gitlab) before a +new version of GitLab UI is released. There are several reasons to do that, such as addressing breaking +changes introduced by the component. + +After creating the new component’s Merge Request and the CI pipeline passes, run the +`create_integration_branch` [manual CI job](https://gitlab.com/gitlab-org/gitlab-ui/pipelines). This job creates or updates a branch in +[GitLab](https://gitlab.com/gitlab-org/gitlab) and replace the stable version of GitLab UI in +the master branch with the package built by the `build_package` CI job in the new component +Merge Request. You would then only need to create a new Merge Request from that branch by +following the link at the end of the `create_integration_branch` job's output. + +Once you create the GitLab integration Merge Request, create a note in the GitLab UI Merge Request with +a link pointing to it. In that way, the code reviewers can use the integration Merge Request to run their +own verifications. diff --git a/doc/images/update_screenshots.png b/doc/images/update_screenshots.png new file mode 100644 index 0000000000000000000000000000000000000000..b0602f6192fc6c3ea47aff3eed2a06f73ed69bf8 Binary files /dev/null and b/doc/images/update_screenshots.png differ