Merge pull request #942 from armsnyder/workflow-lint-custom

timofurrer · web-flow · commit 582968c8e2e0 · 2022-03-09T07:39:57.000+01:00
Workflows: Lint docs for upstream API link
diff --git a/.github/workflows/pr-lint.yml b/.github/workflows/pr-lint.yml
@@ -32,6 +32,7 @@ jobs:
           - lint-examples-tf
           - lint-examples-sh
           - lint-generated
+          - lint-custom
     steps:
       - uses: actions/setup-go@v2
         with:
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
@@ -44,6 +44,7 @@ jobs:
           - lint-examples-tf
           - lint-examples-sh
           - lint-generated
+          - lint-custom
     steps:
       - uses: actions/setup-go@v2
         with:
diff --git a/GNUmakefile b/GNUmakefile
@@ -51,6 +51,9 @@ lint-generated: generate ## Check that "make generate" was called. Note this onl
 		exit 1; \
 	}
 
+lint-custom: ## Run custom checks and validations that do not fit into an existing lint framework.
+	@./scripts/lint-custom.sh
+
 apicovered: tool-apicovered ## Run an analysis tool to estimate the GitLab API coverage.
 	@$(GOBIN)/apicovered ./gitlab
 
diff --git a/docs/data-sources/project_issue.md b/docs/data-sources/project_issue.md
@@ -11,7 +11,7 @@ description: |-
 
 The `gitlab_project_issue` data source allows to retrieve details about an issue in a project.
 
-**Upstream API:** [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
 
 ## Example Usage
 
diff --git a/docs/data-sources/project_issues.md b/docs/data-sources/project_issues.md
@@ -11,7 +11,7 @@ description: |-
 
 The `gitlab_project_issues` data source allows to retrieve details about issues in a project.
 
-**Upstream API:** [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
 
 ## Example Usage
 
diff --git a/docs/data-sources/project_tag.md b/docs/data-sources/project_tag.md
@@ -4,14 +4,14 @@ page_title: "gitlab_project_tag Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
   The gitlab_project_tag data source allows details of a project tag to be retrieved by its name.
-  Upstream API : GitLab API docs https://docs.gitlab.com/ee/api/tags.html
+  Upstream API: GitLab API docs https://docs.gitlab.com/ee/api/tags.html
 ---
 
 # gitlab_project_tag (Data Source)
 
 The `gitlab_project_tag` data source allows details of a project tag to be retrieved by its name.
 
-**Upstream API** : [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)
 
 ## Example Usage
 
diff --git a/docs/resources/group.md b/docs/resources/group.md
@@ -5,13 +5,17 @@ subcategory: ""
 description: |-
   This resource allows you to create and manage GitLab groups.
   Note your provider will need to be configured with admin-level access for this resource to work.
+  Upstream API: GitLab Groups API https://docs.gitlab.com/ee/api/groups.html
 ---
 
 # gitlab_group (Resource)
 
 This resource allows you to create and manage GitLab groups.
+
 Note your provider will need to be configured with admin-level access for this resource to work.
 
+**Upstream API**: [GitLab Groups API](https://docs.gitlab.com/ee/api/groups.html)
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/resources/project_issue.md b/docs/resources/project_issue.md
@@ -17,7 +17,7 @@ The `gitlab_project_issue` resource allows to manage the lifecycle of an issue w
 
 ~> **Experimental**: while the base functionality of this resource works, it may be subject to minor change.
 
-**Upstream API:** [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
 
 ## Example Usage
 
diff --git a/docs/resources/project_tag.md b/docs/resources/project_tag.md
@@ -4,14 +4,14 @@ page_title: "gitlab_project_tag Resource - terraform-provider-gitlab"
 subcategory: ""
 description: |-
   The gitlab_project_tag resource allows to manage the lifecycle of a tag in a project.
-  Upstream API : GitLab API docs https://docs.gitlab.com/ee/api/tags.html
+  Upstream API: GitLab API docs https://docs.gitlab.com/ee/api/tags.html
 ---
 
 # gitlab_project_tag (Resource)
 
 The `gitlab_project_tag` resource allows to manage the lifecycle of a tag in a project.
 
-**Upstream API** : [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)
 
 ## Example Usage
 
diff --git a/internal/provider/data_source_gitlab_project_issue.go b/internal/provider/data_source_gitlab_project_issue.go
@@ -12,7 +12,7 @@ var _ = registerDataSource("gitlab_project_issue", func() *schema.Resource {
 	return &schema.Resource{
 		Description: `The ` + "`gitlab_project_issue`" + ` data source allows to retrieve details about an issue in a project.
 
-**Upstream API:** [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)`,
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)`,
 
 		ReadContext: dataSourceGitlabProjectIssueRead,
 		Schema:      datasourceSchemaFromResourceSchema(gitlabProjectIssueGetSchema(), "project", "iid"),
diff --git a/internal/provider/data_source_gitlab_project_issues.go b/internal/provider/data_source_gitlab_project_issues.go
@@ -31,7 +31,7 @@ var _ = registerDataSource("gitlab_project_issues", func() *schema.Resource {
 	return &schema.Resource{
 		Description: `The ` + "`gitlab_project_issues`" + ` data source allows to retrieve details about issues in a project.
 
-**Upstream API:** [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)`,
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)`,
 
 		ReadContext: dataSourceGitlabProjectIssuesRead,
 		Schema: map[string]*schema.Schema{
diff --git a/internal/provider/data_source_gitlab_project_tag.go b/internal/provider/data_source_gitlab_project_tag.go
@@ -13,7 +13,7 @@ var _ = registerDataSource("gitlab_project_tag", func() *schema.Resource {
 	return &schema.Resource{
 		Description: `The ` + "`gitlab_project_tag`" + ` data source allows details of a project tag to be retrieved by its name.
 
-**Upstream API** : [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)`,
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)`,
 
 		ReadContext: dataSourceGitlabProjectTagRead,
 		Schema: map[string]*schema.Schema{
diff --git a/internal/provider/resource_gitlab_group.go b/internal/provider/resource_gitlab_group.go
@@ -17,8 +17,9 @@ import (
 
 var _ = registerResource("gitlab_group", func() *schema.Resource {
 	return &schema.Resource{
-		Description: "This resource allows you to create and manage GitLab groups.\n" +
-			"Note your provider will need to be configured with admin-level access for this resource to work.",
+		Description: "This resource allows you to create and manage GitLab groups.\n\n" +
+			"Note your provider will need to be configured with admin-level access for this resource to work.\n\n" +
+			"**Upstream API**: [GitLab Groups API](https://docs.gitlab.com/ee/api/groups.html)",
 
 		CreateContext: resourceGitlabGroupCreate,
 		ReadContext:   resourceGitlabGroupRead,
diff --git a/internal/provider/resource_gitlab_project_issue.go b/internal/provider/resource_gitlab_project_issue.go
@@ -25,7 +25,7 @@ var _ = registerResource("gitlab_project_issue", func() *schema.Resource {
 
 ~> **Experimental**: while the base functionality of this resource works, it may be subject to minor change.
 
-**Upstream API:** [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/issues.html)
 		`,
 
 		CreateContext: resourceGitlabProjectIssueCreate,
diff --git a/internal/provider/resource_gitlab_project_tag.go b/internal/provider/resource_gitlab_project_tag.go
@@ -13,7 +13,7 @@ var _ = registerResource("gitlab_project_tag", func() *schema.Resource {
 	return &schema.Resource{
 		Description: `The ` + "`gitlab_project_tag`" + ` resource allows to manage the lifecycle of a tag in a project.
 
-**Upstream API** : [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)`,
+**Upstream API**: [GitLab API docs](https://docs.gitlab.com/ee/api/tags.html)`,
 
 		CreateContext: resourceGitlabProjectTagCreate,
 		ReadContext:   resourceGitlabProjectTagRead,
diff --git a/scripts/lint-custom.sh b/scripts/lint-custom.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+
+# This script is run during the CI workflow in order to run additional custom checks and validations
+# that do not fit into an existing lint framework.
+#
+# This script uses GitHub workflow commands in order to add contextual error messages:
+#   https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message
+#
+# Usage:
+#   ./scripts/lint-custom.sh
+
+has_failure=''
+
+pattern="^\*\*Upstream API\*\*: \[.*\](.*)$"
+files_without_match="$(grep --recursive --files-without-match "$pattern" ./docs/resources ./docs/data-sources)"
+test -z "$files_without_match" || {
+    has_failure='true'
+    echo "$files_without_match" | xargs -I{} echo "::error file={}::Generated documentation file {} should reference an upstream GitLab API. Expected file to match regex \"$pattern\"."
+}
+
+# ^^^ Add new checks above this line ^^^
+
+test -z "$has_failure"

Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,9 @@ lint-generated: generate ## Check that "make generate" was called. Note this onl`
`51`	`51`	`exit 1; \`
`52`	`52`	`}`
`53`	`53`
	`54`	`+lint-custom: ## Run custom checks and validations that do not fit into an existing lint framework.`
	`55`	`+ @./scripts/lint-custom.sh`
	`56`	`+`
`54`	`57`	`apicovered: tool-apicovered ## Run an analysis tool to estimate the GitLab API coverage.`
`55`	`58`	`@$(GOBIN)/apicovered ./gitlab`
`56`	`59`