gitlab-org--gitlab-foss/doc/development/project_templates.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

133 lines
6.1 KiB
Markdown
Raw Normal View History

---
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/product/ux/technical-writing/#assignments"
---
# Contribute a built-in project template
This page provides instructions about how to contribute a
[built-in project template](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template).
To contribute a built-in project template, you must complete the following tasks:
1. [Create a project template for GitLab review](#create-a-project-template-for-review)
1. [Add the template SVG icon to GitLab SVGs](#add-the-template-svg-icon-to-gitlab-svgs)
1. [Create a merge request with vendor details](#create-a-merge-request-with-vendor-details)
You can contribute the following types of project templates:
- Enterprise: For users with GitLab Premium and above.
- Non-enterprise: For users with GitLab Free and above.
## Prerequisites
To add or update an existing template, you must have the following tools
installed:
- `wget`
- `tar`
## Create a project template for review
1. In your selected namespace, create a public project.
1. Add the project content you want to use in the template. Do not include unnecessary assets or dependencies. For an example,
[see this project](https://gitlab.com/gitlab-org/project-templates/dotnetcore).
1. When the project is ready for review, [create an 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](https://about.gitlab.com/handbook/product/categories/#source-code-group)
for the Templates feature.
## Add the template SVG icon to GitLab SVGs
If the project template has an SVG icon, you must add it to the
[GitLab SVGs project](https://gitlab.com/gitlab-org/gitlab-svgs/-/blob/main/README.md#adding-icons-or-illustrations)
before you can create a merge request with vendor details.
## Create a merge request with vendor details
Before GitLab can implement the project template, you must [create a merge request](../user/project/merge_requests/creating_merge_requests.md) in [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) that includes vendor details about the project.
1. [Export the project](../user/project/settings/import_export.md#export-a-project-and-its-data)
and save the file as `<name>.tar.gz`, where `<name>` is the short name of the project.
Move this file to the root directory of `gitlab-org/gitlab`.
1. In `gitlab-org/gitlab`, create and checkout a new branch.
1. Edit the following files to include the project template:
- For **non-Enterprise** project templates:
- In `lib/gitlab/project_template.rb`, add details about 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 project doesn't have an SVG icon, exclude `, 'illustrations/logos/hugo.svg'`.
- In `spec/support/helpers/project_template_test_helper.rb`, append the short name
of the template in the `all_templates` method.
- In `app/assets/javascripts/projects/default_project_templates.js`,
add details of the template. For example:
```javascript
hugo: {
text: s__('ProjectTemplates|Pages/Hugo'),
icon: '.template-option .icon-hugo',
},
```
If the project doesn't have an SVG icon, use `.icon-gitlab_logo`
instead.
- For **Enterprise** project templates:
- In `ee/lib/ee/gitlab/project_template.rb`, in the `localized_ee_templates_table` method, add details about the template. 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')
```
- In `ee/spec/lib/gitlab/project_template_spec.rb`, add the short name
of the template in the `.all` test.
- In `ee/app/assets/javascripts/projects/default_project_templates.js`,
add the template details. For example:
```javascript
hipaa_audit_protocol: {
text: s__('ProjectTemplates|HIPAA Audit Protocol'),
icon: '.template-option .icon-hipaa_audit_protocol',
},
```
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>\]
```
1. Regenerate `gitlab.pot`:
```shell
bin/rake gettext:regenerate
```
1. After you run the scripts, there is one new file in `vendor/project_templates/` and four changed files. Commit all changes and push your branch to update the merge request. For an example, see this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318).
## Test your built-in project with the GitLab Development Kit
Complete the following steps to test the project template in your own GitLab Development Kit instance:
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>\]
```
## Contribute an improvement to an existing template
To update an existing built-in project template:
1. Create a merge request in the relevant project of the `project-templates` and `pages` group and mention `@gitlab-org/manage/import/backend` when you are ready for a review.
1. If your merge request is accepted, either:
- [Create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues) to ask for the template to get updated.
- [Create a merge request with vendor details](#create-a-merge-request-with-vendor-details) to update the template.