Merge branch '246857-requirements-management-import-csv-docs' into 'master'

Document importing requirements from CSV file

See merge request gitlab-org/gitlab!47439

doc/user/project/requirements/index.md

@@ -30,9 +30,11 @@ For an overview, see [GitLab 12.10 Introduces Requirements Management](https://w
 A paginated list of requirements is available in each project, and there you
 can create a new requirement.
 
+Users with Reporter or higher [permissions](../../permissions.md) can create requirements.
+
 To create a requirement:
 
-1. From your project page, go to **{requirements}** **Requirements**.
+1. From your project page, go to **Requirements**.
 1. Select **New requirement**.
 1. Enter a title and description and select **Create requirement**.
 
@@ -54,8 +56,9 @@ next to the requirement title.
 
 > The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5.
 
-You can edit a requirement (if you have the necessary privileges) from the requirements
-list page.
+You can edit a requirement from the requirements list page.
+
+Users with Reporter or higher [permissions](../../permissions.md) can edit requirements.
 
 To edit a requirement:
 
@@ -66,9 +69,11 @@ To edit a requirement:
 
 ## Archive a requirement
 
-You can archive an open requirement (if you have the necessary privileges) while
+You can archive an open requirement while
 you're in the **Open** tab.
 
+Users with Reporter or higher [permissions](../../permissions.md) can archive requirements.
+
 To archive a requirement, select **Archive** (**{archive}**).
 
 As soon as a requirement is archived, it no longer appears in the **Open** tab.
@@ -77,6 +82,8 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab.
 
 You can view the list of archived requirements in the **Archived** tab.
 
+Users with Reporter or higher [permissions](../../permissions.md) can reopen archived requirements.
+
 ![archived requirements list](img/requirements_archived_list_view_v13_1.png)
 
 To reopen an archived requirement, select **Reopen**.
@@ -94,7 +101,7 @@ You can search for a requirement from the requirements list page based on the fo
 
 To search for a requirement:
 
-1. In a project, go to **{requirements}** **Requirements > List**.
+1. In a project, go to  **Requirements > List**.
 1. Select the **Search or filter results** field. A dropdown menu appears.
 1. Select the requirement author from the dropdown or enter plain text to search by requirement title.
 1. Press <kbd>Enter</kbd> on your keyboard to filter the list.
@@ -188,3 +195,65 @@ requirements_confirmation:
     reports:
       requirements: tmp/requirements.json
 ```
+
+## Import requirements from a CSV file
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7.
+
+You can import requirements to a project by uploading a CSV file with the columns
+`title` and `description`.
+
+The user uploading the CSV file will be set as the author of the imported requirements.
+
+Users with Reporter or higher [permissions](../../permissions.md) can import requirements.
+
+### Import the file
+
+Before you import your file:
+
+- Consider importing a test file containing only a few requirements. There is no way to undo a large
+  import without using the GitLab API.
+- Ensure your CSV file meets the [file format](#csv-file-format) requirements.
+
+To import requirements:
+
+1. Navigate to a project's Requirements page.
+   - If the project already has existing requirements, click the import icon (**{import}**) at the
+     top right.
+   - For a project without any requirements, click **Import CSV** in the middle of the page.
+1. Select the file and click **Import requirements**.
+
+The file is processed in the background and a notification email is sent
+to you after the import is complete.
+
+### CSV file format
+
+When importing requirements from a CSV file, it must be formatted in a certain way:
+
+- **Header row:** CSV files must include the following headers:
+  `title` and `description`. The headers are case insensitive.
+- **Columns:** data from columns other than `title` and `description` is not imported.
+- **Separators:** the column separator is automatically detected from the header row.
+  Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`).
+  The row separator can be either `CRLF` or `LF`.
+- **Double-quote character:** the double-quote (`"`) character is used to quote fields,
+  enabling the use of the column separator in a field (see the third line in the
+  sample CSV data below). To insert a double-quote (`"`) in a quoted
+  field, use two double-quote characters in succession (`""`).
+- **Data rows:** below the header row, succeeding rows must follow the same column
+  order. The title text is required, while the description is optional and can be left empty.
+
+Sample CSV data:
+
+```plaintext
+title,description
+My Requirement Title,My Requirement Description
+Another Title,"A description, with a comma"
+"One More Title","One More Description"
+```
+
+### File size
+
+The limit depends on the configuration value of Max Attachment Size for the GitLab instance.
+
+For GitLab.com, it is set to 10 MB.

ee/app/views/notify/import_requirements_csv_email.html.haml

@@ -16,6 +16,5 @@
 - if @results[:parse_error]
   %p{ style: text_style }
     = _('Error parsing CSV file. Please make sure it has')
-    %a{ href: help_page_url('user/project/issues/csv_import', anchor: 'csv-file-format') }
+    %a{ href: help_page_url('user/project/requirements/index.md', anchor: 'csv-file-format') }
       = _('the correct format.')
-

ee/app/views/notify/import_requirements_csv_email.text.erb

@@ -7,5 +7,5 @@ Errors found on line <%= 'number'.pluralize(@results[:error_lines].size) %>: <%=
 <% end %>
 
 <% if @results[:parse_error] %>
-Error parsing CSV file. Please make sure it has the correct format (<%= help_page_url('user/project/issues/csv_import', anchor: 'csv-file-format') %>).
+Error parsing CSV file. Please make sure it has the correct format (<%= help_page_url('user/project/requirements/index.html', anchor: 'csv-file-format') %>).
 <% end %>