157 lines
6.3 KiB
Markdown
157 lines
6.3 KiB
Markdown
---
|
|
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).
|