diff options
Diffstat (limited to 'doc/user/project/issues/design_management.md')
| -rw-r--r-- | doc/user/project/issues/design_management.md | 330 |
1 files changed, 174 insertions, 156 deletions
diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index e7bb5ad4eeb..e5dde0ed451 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -9,259 +9,265 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. > - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. +> - Design Management section in issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, with a feature flag named `design_management_moved`. In earlier versions, designs were displayed in a separate tab. +> - Design Management section in issues [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. -Design Management allows you to upload design assets (including wireframes and mockups) -to GitLab issues and keep them stored in a single place, accessed by the Design -Management's page within an issue, giving product designers, product managers, and engineers a -way to collaborate on designs over a single source of truth. +With Design Management you can upload design assets (including wireframes and mockups) +to GitLab issues and keep them stored in a single place. Product designers, product managers, and +engineers can collaborate on designs with a single source of truth. -You can share mock-ups of designs with your team, or visual regressions can be +You can share mockups of designs with your team, or visual regressions can be viewed and addressed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the video [Design Management (GitLab 12.2)](https://www.youtube.com/watch?v=CCMtCqdK_aM). +For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube.com/watch?v=CCMtCqdK_aM). ## Requirements -Design Management requires -[Large File Storage (LFS)](../../../topics/git/lfs/index.md) -to be enabled: +- [Git Large File Storage (LFS)](../../../topics/git/lfs/index.md) must be enabled: + - On GitLab.com, LFS is already enabled. + - On self-managed instances, a GitLab administrator must + [enable LFS globally](../../../administration/lfs/index.md). + - On both GitLab.com and self-managed instances, LFS must be + [enabled for the project itself](../settings/index.md#sharing-and-permissions). + If enabled globally, LFS is enabled by default for all projects. If you have + disabled it for your project, you must enable it again. -- For GitLab.com, LFS is already enabled. -- For self-managed instances, a GitLab administrator must have - [enabled LFS globally](../../../administration/lfs/index.md). -- For both GitLab.com and self-managed instances: LFS must be enabled for the project itself. - If enabled globally, LFS is enabled by default to all projects. To enable LFS on the - project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions** - and enable **Git Large File Storage**. + Designs are stored as LFS objects. + Image thumbnails are stored as other uploads, and are not associated with a project but rather + with a specific design model. -Design Management also requires that projects are using -[hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). -Newly created projects use hashed storage by default. A GitLab administrator -can verify the storage type of a project by going to **Admin Area > Projects** -and then selecting the project in question. A project can be identified as -hashed-stored if its *Gitaly relative path* contains `@hashed`. +- Projects must use + [hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). -If the requirements are not met, the **Designs** tab displays a message to the user. + Newly created projects use hashed storage by default. -## Supported files + A GitLab administrator can verify the storage type of a project by going to **Admin Area > Projects** + and then selecting the project in question. A project can be identified as + hashed-stored if its **Gitaly relative path** contains `@hashed`. -Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, -`gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. +If the requirements are not met, you are notified in the **Designs** section. -Support for PDF is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/32811). +## Supported file types -## Limitations +You can upload files of the following types as designs: -- Design uploads are limited to 10 files at a time. -- From GitLab 13.1, Design filenames are limited to 255 characters. -- Design Management data - [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. -- Design Management data [isn't deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) - when an issue is deleted. -- From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) +- BMP +- GIF +- ICO +- JPEG +- JPG +- PNG +- SVG +- TIFF +- WEBP + +Support for PDF files is tracked in [issue 32811](https://gitlab.com/gitlab-org/gitlab/-/issues/32811). + +## Known issues + +- Design Management data isn't deleted when: + - [A project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429). + - [An issue is deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427). +- In GitLab 12.7 and later, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). -- Only the latest version of the designs can be deleted. -- Deleted designs cannot be recovered but you can see them on previous designs versions. -## GitLab-Figma plugin +## View a design -> [Introduced](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/issues/2) in GitLab 13.2. +The **Designs** section is in the issue description. + +Prerequisites: + +- You must have at least the Guest role for the project. + +To view a design: + +1. Go to an issue. +1. In the **Designs** section, select the design image you want to view. + +The design you selected opens. You can then [zoom in](#zoom-in-on-a-design) on it or +[create a comment](#add-a-comment-to-a-design). -Connect your design environment with your source code management in a seamless workflow. The GitLab-Figma plugin makes it quick and easy to collaborate in GitLab by bringing the work of product designers directly from Figma to GitLab Issues as uploaded Designs. + -To use the plugin, install it from the [Figma Directory](https://www.figma.com/community/plugin/860845891704482356) -and connect to GitLab through a personal access token. The details are explained in the [plugin documentation](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/wikis/home). +When viewing a design, you can move to other designs. To do so, either: -## The Design Management section +- In the top-right corner, select **Go to previous design** (**{angle-left}**) or **Go to next design** (**{angle-right}**). +- Press <kbd>Left</kbd> or <kbd>Right</kbd> on your keyboard. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2. Designs are displayed directly in the issue description instead of a separate tab. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. +To return to the issue view, either: -You can find to the **Design Management** section in the issue description: +- In the top-left corner, select the close icon (**{close}**). +- Press <kbd>Esc</kbd> on your keyboard. - +When a design is added, a green icon (**{plus-square}**) is displayed on the image +thumbnail. When a design has been [changed](#add-a-new-version-of-a-design) in the current version, +a blue icon (**{file-modified-solid}**) is displayed. -## Adding designs +### Zoom in on a design + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. +> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. + +You can explore a design in more detail by zooming in and out of the image: + +- To control the amount of zoom, select plus (`+`) and minus (`-`) + at the bottom of the image. +- To reset the zoom level, select the redo icon (**{redo}**). + +To move around the image while zoomed in, drag the image. + +## Add a design to an issue > - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. > - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. > - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. -To upload Design images, drag files from your computer and drop them in the Design Management section, -or select **click to upload** to select images from your file browser: +Prerequisites: - +- You must have at least the Developer role for the project. +- In GitLab 13.1 and later, the names of the uploaded files must be no longer than 255 characters. -You can drag and drop designs onto the dedicated drop zone to upload them. +To add a design to an issue: - +1. Go to an issue. +1. Either: + - Select **Upload designs** and then select images from your file browser. You can select up to + 10 files at once. + <!-- vale gitlab.SubstitutionWarning = NO --> + - Select **click to upload** and then select images from your file browser. You can select up to + 10 files at once. + <!-- vale gitlab.SubstitutionWarning = YES --> -You can also copy images from your file system and paste them directly on the -GitLab Design page as a new design. + - Drag a file from your file browser and drop it in the drop zone in the **Designs** section. -On macOS, you can take a screenshot and immediately copy it to the clipboard -by simultaneously pressing <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, -and then paste it as a design. +  -Copy-and-pasting has some limitations: + - Take a screenshot or copy a local image file into your clipboard, hover your cursor over the + drop zone, and press <kbd>Control</kbd> or <kbd>Cmd</kbd> + <kbd>V</kbd>. -- You can paste only one image at a time. When copy/pasting multiple files, only the first one is uploaded. -- All images are converted to `png` format under the hood, so when you want to copy/paste `gif` file, it results in broken animation. -- If you are pasting a screenshot from the clipboard, it is renamed to `design_<timestamp>.png` -- Copy/pasting designs is not supported on Internet Explorer. + When pasting images like this, keep the following in mind: -Designs with the same filename as an existing uploaded design create a new version -of the design, and replaces the previous version. Dropping a design on an -existing uploaded design creates a new version if the filenames are the same. - -### Skipped designs + - You can paste only one image at a time. When you paste multiple copied files, only the first + one is uploaded. + - If you are pasting a screenshot, the image is added as a PNG file with a generated name of: + `design_<timestamp>.png`. + - It's not supported in Internet Explorer. -Designs with the same filename as an existing uploaded design _and_ whose content has not changed are skipped. -This means that no new version of the design is created. When designs are skipped, you are made aware by a warning -message on the Issue. +## Add a new version of a design -## Viewing designs +As discussion on a design continues, you might want to upload a new version of a design. -Images on the Design Management page can be enlarged by selecting them. -You can navigate through designs by selecting the navigation buttons on the -top-right corner or with <kbd>Left</kbd>/<kbd>Right</kbd> keyboard buttons. +Prerequisites: -The number of discussions on a design — if any — is listed to the right -of the design filename. Selecting this number enlarges the design, -similar to clicking or tapping anywhere else in the design. -When a design is added or modified, an icon is displayed on the item -to help summarize changes between versions. +- You must have at least the Developer role for the project. -| Indicator | Example | -| --------- | ------- | -| Discussions |  | -| Modified (in the selected version) |  | -| Added (in the selected version) |  | +To do so, [add a design](#add-a-design-to-an-issue) with the same filename. -### Exploring designs by zooming +To browse all the design versions, use the dropdown list at the top of the **Designs** section. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. -> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. - -Designs can be explored in greater detail by zooming in and out of the image. -Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. -While zoomed, you can still [start new discussions](#starting-discussions-on-designs) on the image, and see any existing ones. -While zoomed in, you can drag the image to move around it. +### Skipped designs - +When you upload an image with the same filename as an existing uploaded design _and_ that is the +same, it's skipped. This means that no new version of the design is created. +When designs are skipped, a warning message is displayed. -## Deleting designs +## Archive a design > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/220964) the button from "Delete" to "Archive" in GitLab 13.3. -There are two ways to delete designs: manually delete them -individually, or select a few of them to delete at once, -as shown below. +You can archive individual designs or select a few of them to archive at once. -To delete a single design, select it to view it enlarged, -then select the trash icon on the top right corner and confirm -the deletion by selecting **Delete** in the window: +Prerequisites: - +- You must have at least the Developer role for the project. -To delete multiple designs at once, on the design's list view, -first select the designs you want to delete: +To archive a single design: - +1. Select the design to view it enlarged. +1. In the top right corner, select **Archive design** (**{archive}**). +1. Select **Archive designs**. -Select **Delete selected** to confirm the deletion: +To archive multiple designs at once: - +1. Select the checkboxes on the designs you want to archive. +1. Select **Archive selected**. NOTE: -Only the latest version of the designs can be deleted. -Deleted designs are not permanently lost; they can be -viewed by browsing previous versions. +Only the latest version of the designs can be archived. +Archived designs are not permanently lost. You can browse +[previous versions](#add-a-new-version-of-a-design). -## Reordering designs +## Reorder designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. You can change the order of designs by dragging them to a new position. -## Starting discussions on designs - -> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) adjusting a pin's position in GitLab 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. +## Add a comment to a design -When a design is uploaded, you can start a discussion by selecting -the image on the exact location you would like the discussion to be focused on. -A pin is added to the image, identifying the discussion's location. +> Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.8. - +You can start [discussions](../../discussions/index.md) on uploaded designs. To do so: -You can adjust a pin's position by dragging it around the image. This is useful -for when your design layout has changed between revisions, or if you need to move an -existing pin to add a new one in its place. +<!-- vale gitlab.SubstitutionWarning = NO --> +1. Go to an issue. +1. Select the design. +1. Click or tap the image. A pin is created in that spot, identifying the discussion's location. +1. Enter your message. +1. Select **Comment**. +<!-- vale gitlab.SubstitutionWarning = YES --> -Different discussions have different pin numbers: +You can adjust a pin's position by dragging it around the image. You can use this when your design's +layout has changed, or when you want to move a pin to add a new one in its place. - +New discussion threads get different pin numbers, which you can use to refer to them. In GitLab 12.5 and later, new discussions are output to the issue activity, so that everyone involved can participate in the discussion. -## Resolve Design threads +## Resolve a discussion thread on a design > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. -Discussion threads can be resolved on Designs. - -There are two ways to resolve/unresolve a Design thread: - -1. You can mark a thread as resolved or unresolved by selecting the checkmark icon for **Resolve thread** in the top-right corner of the first comment of the discussion: +When you're done discussing part of a design, you can resolve the discussion thread. -  +To mark a thread as resolved or unresolved, either: -1. Design threads can also be resolved or unresolved in their threads by using a checkbox. - When replying to a comment, you can select or clear a checkbox to resolve or unresolve - the thread after publishing: +- In the top-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). +- Add a new comment to the thread and select or clear the **Resolve thread** checkbox. -  +Resolving a discussion thread also marks any pending [to-do items](../../todos.md) related to notes +inside the thread as done. Only to-do items for the user triggering the action are affected. -Resolving a discussion thread also marks any pending to-do items related to notes -inside the thread as done. This is applicable only for to-do items owned by the user triggering the action. +Your resolved comment pins disappear from the design to free up space for new discussions. +To revisit a resolved discussion, expand **Resolved Comments** below the visible threads. -Your resolved comment pins disappear from the Design to free up space for new discussions. -However, if you need to revisit or find a resolved discussion, all of your resolved threads are -available in the **Resolved Comment** area at the bottom of the right sidebar. - -## Add to-do items for designs +## Add a to-do item for a design > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -Add a to-do item for a design by selecting **Add a to do** on the design sidebar: - - +To add a [to-do item](../../todos.md) for a design, select **Add a to do** on the design sidebar. -## Referring to designs in Markdown +## Refer to a design in Markdown > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in GitLab 13.1. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in GitLab 13.5. -We support referring to designs in [Markdown](../../markdown.md), which is available -throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. +To refer to a design in a [Markdown](../../markdown.md) text box in GitLab, for example, in +a comment or description, paste its URL. It's then displayed as a short reference. -Full URL references are supported. For example, if we refer to a design -somewhere with: +For example, if you refer to a design somewhere with: ```markdown -See https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png +See https://gitlab.com/gitlab-org/gitlab/-/issues/13195/designs/Group_view.png. ``` -This is rendered as: +It's rendered as: -> See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) +> See [#13195[Group_view.png]](https://gitlab.com/gitlab-org/gitlab/-/issues/13195/designs/Group_view.png). ## Design activity records @@ -272,3 +278,15 @@ User activity events on designs (creation, deletion, and updates) are tracked by displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#view-project-activity) activity pages. + +## GitLab-Figma plugin + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/issues/2) in GitLab 13.2. + +You can use the GitLab-Figma plugin to upload your designs from Figma directly to your issues +in GitLab. + +To use the plugin in Figma, install it from the [Figma Directory](https://www.figma.com/community/plugin/860845891704482356) +and connect to GitLab through a personal access token. + +For more information, see the [plugin documentation](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/wikis/home). |