## Overview Welcome! This migration epic is a little unlike some of the others. Here we're migrating older, deprecated GitLab UI components to newer, better ones. Dropdowns are a hard problem to solve so we've split our dropdown component into several pieces to be used where appropriate. `<GlCollapsibleListbox>` is your standard dropdown. It's a button that toggles a panel containing a list of options. In this epic, we've identified uses of the deprecated `<GlDropdown>` that are migratable to `<GlCollapsibleListbox>`. ## Migration Instructions 1. Pick an issue, any issue. It doesn't have to be from your group or area of the codebase. 2. That issue will point to a specific file. Look for the use of `<GlDropdown>` in there. This is what we need to replicate. 3. Find where that component is rendered in the application and take some before screenshots. We'll need to compare the old behavior to the new behavior. 4. Take a look at the [GitLab UI documentation for `<GlCollapsibleListbox>`](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/base-new-dropdowns-listbox--default#custom-list-item) and make sure it can do what you need it to (Note: the docs may call this component `<GlListBox>`, they're the same thing, more on that later) 5. Start plugging in the data, attributes, and whatever else you need to get the migration working. There's some gotchas I'll list below, check them out if you're stuck. 6. Make sure the tests pass. The underlying markdown is a little different between the two implementations so some of the rspec tests may be looking in the wrong place. 7. Take some "after" screenshots and create your MR. Anyone can review this, it doesn't have to be the foundations team. 8. Rejoice. Your migration is complete and you've helped make GitLab a better place. ## Things to know Nothing ever goes according to plan, but here's some tips to help you when it doesn't. 1. A main difference between these two components is the way we pass the data to them. `<GlDropdown>` wraps a `<GlDropdownItem>` that we loop over with `v-for`. With `<GlCollapsibleListbox>` you pass the items in as an array to the `item` prop. You may need to do some array reshuffling to get the data in the format you need. See [the documentation](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/base-new-dropdowns-listbox--default#custom-list-item) for more info but the basic structure is, `[{ value, text },{ value, text }]`. 2. Your rspec tests will likely fail. It will also likely be because list items used to be a `<p>` tag and are now (more appropriately) `<span>`s. Make sure rspec is looking for the correct element. 3. `<GlCollapsibleListbox>` used to be called `<GlListbox>`. It's in the [process of being renamed](https://gitlab.com/groups/gitlab-org/-/epics/9091), but for now they're interchangeable. Right now, either will work, but please use `<GlCollapsibleListbox>` to save us having to update it later. 4. Finding where these components live in the application is often the biggest challenge. If you're struggling to find it, check the blame, reach out to #frontend on slack, or move on to another component. 5. If you do move on to another component for whatever reason. Be sure to mention that reason in the issue. Let's prevent people from running into the same problems you did and getting frustrated. 6. The foundations team are always here to help. Tag us on the issue `@gitlab-org/manage/foundations/engineering` , reach out on slack `#g_manage-foundations`, or look in the mirror and say "Pajamas" three times. Then do one of the first two options. 7. To show how to do these migrations—from picking up the issue, to writing the code, fixing the tests, and submitting the MR—Sam screencast himself doing one. If you're unsure what to do, or are curious how other's have done these, take a look. It's only 40 minutes long so that should show you just how quickly these migration can be done. <https://youtu.be/lmfElD7haHY>