diff options
Diffstat (limited to 'doc/user/project/requirements/index.md')
| -rw-r--r-- | doc/user/project/requirements/index.md | 105 |
1 files changed, 94 insertions, 11 deletions
diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 50343e52a68..d9bd02518a4 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,14 +1,23 @@ --- type: reference, howto +stage: Plan +group: Certify +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Requirements **(ULTIMATE)** +# Requirements Management **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -Requirements allow you to create criteria to check your products against. They -can be based on users, stakeholders, system, software, or anything else you -find important to capture. +With requirements, you can set criteria to check your products against. They can be based on users, +stakeholders, system, software, or anything else you find important to capture. + +A requirement is an artifact in GitLab which describes the specific behavior of your product. +Requirements are long-lived and don't disappear unless manually cleared. + +If an industry standard *requires* that your application has a certain feature or behavior, you can +[create a requirement](#create-a-requirement) to reflect this. +When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). @@ -38,22 +47,18 @@ list page. To edit a requirement: -1. From the requirements list, click the **Edit** (**{pencil}**) button. +1. From the requirements list, click **Edit** (**{pencil}**). 1. Update the title in text input field. 1. Click **Save changes**.  -The requirements list shows the new title immediately. - - - ## Archive a requirement You can archive an open requirement (if you have the necessary privileges) while you're in the **Open** tab. -From the requirements list page, click the **Archive** (**{archive}**) button. +From the requirements list page, click **Archive** (**{archive}**).  @@ -65,6 +70,84 @@ You can view the list of archived requirements in the **Archived** tab.  -To reopen an archived requirement, click the **Reopen** button. +To reopen an archived requirement, click **Reopen**. As soon as a requirement is reopened, it no longer appears in the **Archived** tab. + +## Search for a requirement from the requirements list page + +> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +You can search for a requirement from the list of requirements using filtered search bar (similar to +that of Issues and Merge Requests) based on following parameters: + +- Title +- Author username + +To search, go to the list of requirements and click the field **Search or filter results**. +It will display a dropdown menu, from which you can add an author. You can also enter plain +text to search by epic title or description. When done, press <kbd>Enter</kbd> on your +keyboard to filter the list. + +You can also sort requirements list by: + +- Created date +- Last updated + +## Allow requirements to be satisfied from a CI job + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +GitLab supports [requirements test +reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements-ultimate) now. +You can add a job to your CI pipeline that, when triggered, marks all existing +requirements as Satisfied. + +### Add the manual job to CI + +To configure your CI to mark requirements as Satisfied when the manual job is +triggered, add the code below to your `.gitlab-ci.yml` file. + +```yaml +requirements_confirmation: + when: manual + allow_failure: false + script: + - mkdir tmp + - echo "{\"*\":\"passed\"}" > tmp/requirements.json + artifacts: + reports: + requirements: tmp/requirements.json +``` + +This definition adds a manually-triggered (`when: manual`) job to the CI +pipeline. It's blocking (`allow_failure: false`), but it's up to you what +conditions you use for triggering the CI job. Also, you can use any existing CI job +to mark all requirements as satisfied, as long as the `requirements.json` +artifact is generated and uploaded by the CI job. + +When you manually trigger this job, the `requirements.json` file containing +`{"*":"passed"}` is uploaded as an artifact to the server. On the server side, +the requirement report is checked for the "all passed" record +(`{"*":"passed"}`), and on success, it marks all existing open requirements as +Satisfied. + +### Add the manual job to CI conditionally + +To configure your CI to include the manual job only when there are some open +requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI variable. + +```yaml +requirements_confirmation: + rules: + - if: "$CI_HAS_OPEN_REQUIREMENTS" == "true" + when: manual + - when: never + allow_failure: false + script: + - mkdir tmp + - echo "{\"*\":\"passed\"}" > tmp/requirements.json + artifacts: + reports: + requirements: tmp/requirements.json +``` |