From e3fc3ef5002679f037f1e27a3293c4ee1d3e92a2 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axil@gitlab.com>
Date: Fri, 1 Apr 2022 18:40:37 +0000
Subject: [PATCH] Document how to add a new built-in project template
- Move the bundle_repo script from
https://gitlab.com/gitlab-org/project-templates/contributing
- Clean up documentation of contriobuting to the built-in templates.
Mostly copy https://about.gitlab.com/community/contribute/project-templates/
and refactor it to be more clear.
Changelog: other
---
doc/development/project_templates.md | 157 +++++++++++++++++++++++++++
scripts/vendor_template | 57 ++++++++++
2 files changed, 214 insertions(+)
create mode 100644 doc/development/project_templates.md
create mode 100755 scripts/vendor_template
diff --git a/doc/development/project_templates.md b/doc/development/project_templates.md
new file mode 100644
index 0000000000000..74ded9c93fc4c
--- /dev/null
+++ b/doc/development/project_templates.md
@@ -0,0 +1,157 @@
+---
+stage: Manage
+group: Workspace
+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/#assignments"
+---
+
+# Contribute to GitLab project templates
+
+Thanks for considering a contribution to the GitLab
+[built-in project templates](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template).
+
+## Prerequisites
+
+To add a new or update an existing template, you must have the following tools
+installed:
+
+- `wget`
+- `tar`
+- `jq`
+
+## Create a new project
+
+To contribute a new built-in project template to be distributed with GitLab:
+
+1. Create a new public project with the project content you'd like to contribute
+ in a namespace of your choosing. You can [view a working example](https://gitlab.com/gitlab-org/project-templates/dotnetcore).
+ Projects should be as simple as possible and free of any unnecessary assets or dependencies.
+1. When the project is ready for review, [create a new issue](https://gitlab.com/gitlab-org/gitlab/issues) with a link to your project.
+ In your issue, `@` mention the relevant Backend Engineering Manager and Product
+ Manager for the [Templates feature](https://about.gitlab.com/handbook/product/categories/#source-code-group).
+
+## Add the SVG icon to GitLab SVGs
+
+If the template you're adding has an SVG icon, you need to first add it to
+<https://gitlab.com/gitlab-org/gitlab-svgs>:
+
+1. Follow the steps outlined in the
+ [GitLab SVGs project](https://gitlab.com/gitlab-org/gitlab-svgs/-/blob/main/README.md#adding-icons-or-illustrations)
+ and submit a merge request.
+1. When the merge request is merged, `gitlab-bot` will pull the new changes in
+ the `gitlab-org/gitlab` project.
+1. You can now continue on the vendoring process.
+
+## Vendoring process
+
+To make the project template available when creating a new project, the vendoring
+process will have to be completed:
+
+1. [Export the project](../user/project/settings/import_export.md#export-a-project-and-its-data)
+ you created in the previous step and save the file as `<name>.tar.gz`, where
+ `<name>` is the short name of the project.
+1. Edit the following files to include the project template. Two types of built-in
+ templates are available within GitLab:
+ - **Normal templates**: Available in GitLab Free and above (this is the most common type of built-in template).
+ See MR [!25318](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) for an example.
+
+ To add a normal template:
+
+ 1. Open `lib/gitlab/project_template.rb` and add details of the template
+ in the `localized_templates_table` method. In the following example,
+ the short name of the project is `hugo`:
+
+ ```ruby
+ ProjectTemplate.new('hugo', 'Pages/Hugo', _('Everything you need to create a GitLab Pages site using Hugo'), 'https://gitlab.com/pages/hugo', 'illustrations/logos/hugo.svg'),
+ ```
+
+ If the vendored project doesn't have an SVG icon, omit `, 'illustrations/logos/hugo.svg'`.
+
+ 1. Open `spec/lib/gitlab/project_template_spec.rb` and add the short name
+ of the template in the `.all` test.
+ 1. Open `app/assets/javascripts/projects/default_project_templates.js` and
+ add details of the template. For example:
+
+ ```javascript
+ hugo: {
+ text: s__('ProjectTemplates|Pages/Hugo'),
+ icon: '.template-option .icon-hugo',
+ },
+ ```
+
+ If the vendored project doesn't have an SVG icon, use `.icon-gitlab_logo`
+ instead.
+
+ - **Enterprise templates**: Introduced in GitLab 12.10, that are available only in GitLab Premium and above.
+ See MR [!28187](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28187) for an example.
+
+ To add an Enterprise template:
+
+ 1. Open `ee/lib/ee/gitlab/project_template.rb` and add details of the template
+ in the `localized_ee_templates_table` method. For example:
+
+ ```ruby
+ ::Gitlab::ProjectTemplate.new('hipaa_audit_protocol', 'HIPAA Audit Protocol', _('A project containing issues for each audit inquiry in the HIPAA Audit Protocol published by the U.S. Department of Health & Human Services'), 'https://gitlab.com/gitlab-org/project-templates/hipaa-audit-protocol', 'illustrations/logos/asklepian.svg')
+ ```
+
+ 1. Open `ee/spec/lib/gitlab/project_template_spec.rb` and add the short name
+ of the template in the `.all` test.
+ 1. Open `ee/app/assets/javascripts/projects/default_project_templates.js` and
+ add details of the template. For example:
+
+ ```javascript
+ hipaa_audit_protocol: {
+ text: s__('ProjectTemplates|HIPAA Audit Protocol'),
+ icon: '.template-option .icon-hipaa_audit_protocol',
+ },
+ ```
+
+1. Run the `vendor_template` script. Make sure to pass the correct arguments:
+
+ ```shell
+ scripts/vendor_template <git_repo_url> <name> <comment>
+ ```
+
+1. Regenerate `gitlab.pot`:
+
+ ```shell
+ bin/rake gettext:regenerate
+ ```
+
+1. By now, there should be one new file under `vendor/project_templates/` and
+ 4 changed files. Commit all of them in a new branch and create a merge
+ request.
+
+## Test with GDK
+
+If you are using the GitLab Development Kit (GDK) you must disable `praefect`
+and regenerate the Procfile, as the Rake task is not currently compatible with it:
+
+```yaml
+# gitlab-development-kit/gdk.yml
+praefect:
+ enabled: false
+```
+
+1. Follow the steps described in the [vendoring process](#vendoring-process).
+1. Run the following Rake task where `<path>/<name>` is the
+ name you gave the template in `lib/gitlab/project_template.rb`:
+
+ ```shell
+ bin/rake gitlab:update_project_templates[<path>/<name>]
+ ```
+
+You can now test to create a new project by importing the new template in GDK.
+
+## Contribute an improvement to an existing template
+
+Existing templates are imported from the following groups:
+
+- [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
+- [`pages`](htps://gitlab.com/pages)
+
+To contribute a change, open a merge request in the relevant project
+and mention `@gitlab-org/manage/import/backend` when you are ready for a review.
+
+Then, if your merge request gets accepted, either [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues)
+to ask for it to get updated, or open a merge request updating
+the [vendored template](#vendoring-process).
diff --git a/scripts/vendor_template b/scripts/vendor_template
new file mode 100755
index 0000000000000..96d013ea772b0
--- /dev/null
+++ b/scripts/vendor_template
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+#
+# Run it as:
+# vendor_template https://gitlab.com/pages/hugo hugo "Pages/Hugo template"
+#
+
+## Check which OS the script runs from since gtar/tar behaves differently
+## on macOS and Linux
+if [ "$(uname)" == "Darwin" ]; then
+ GTAR="gtar"
+else
+ GTAR="tar"
+fi
+
+## Check if jq is installed
+hash jq 2>/dev/null || echo "ERROR: jq is not installed. Install it and run the script again."
+
+REPO_URL=$1
+SHORT_NAME=$2
+COMMENT=$3
+FILENAME="$SHORT_NAME.tar.gz"
+
+# Check if the extracted project exists
+if [ ! -f $FILENAME ]
+then
+ echo
+ echo "ERROR: $FILENAME doesn't exist. Did you export the project?"
+ exit 1
+fi
+
+$GTAR --list --file="$FILENAME"
+rm -rf tar-base project-$SHORT_NAME
+mkdir -p "./tar-base"
+tar xf "$2.tar.gz" -C "./tar-base" ./VERSION ./tree/project.json
+git clone "$REPO_URL" project-$SHORT_NAME
+cd project-$SHORT_NAME
+rm -rf .git
+git init
+git add -A .
+git commit --author "GitLab <root@localhost>" -m "$COMMENT"
+git bundle create project.bundle --all
+mv -f project.bundle ../tar-base/
+cd ../tar-base
+cat tree/project.json | jq '.issues = [] | .releases = [] | .merge_requests = [] | .ci_pipelines = [] | .pipeline_schedules = [] | .services = [] | .pipelines = [] | .protected_branches = [] | .project_members = [] | .labels = [] | del(.ci_cd_settings, .external_authorization_classification_label, .project_feature)' -c > project.json
+rm -rf tree
+ls -alth
+tar cvzf "$FILENAME" ./
+cd ..
+
+echo "=> Moving $FILENAME to the vendored templates"
+mv tar-base/$FILENAME vendor/project_templates/
+
+echo "=> Cleaning up"
+rm -rf tar-base "project-$SHORT_NAME" $FILENAME
+
+echo "=> The following files are included in the bundled repo:"
+$GTAR --list --file="vendor/project_templates/$FILENAME"
--
GitLab