1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
---
stage: Create
group: Source Code
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments"
---
# Contribute to built-in project templates
GitLab provides some
[built-in project templates](../user/project/index.md#create-a-project-from-a-built-in-template)
that you can use when creating a new project.
Built-in templates are sourced from the following groups:
- [`gitlab-org/project-templates`](https://gitlab.com/gitlab-org/project-templates)
- [`pages`](https://gitlab.com/pages)
Prerequisites:
- You must have a working [GitLab Development Kit (GDK) environment](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/index.md).
In particular, PostgreSQL, Praefect, and `sshd` must be working.
- `wget` should be installed.
## Add a new built-in project template
If you'd like to contribute a new built-in project template to be distributed
with GitLab, there are a few steps to follow.
### Create the project
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 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/new) with a link to your project.
- In your issue, `@` mention the relevant Backend Engineering Manager and Product Manager for the [Create:Source Code group](https://handbook.gitlab.com/handbook/product/categories/#source-code-group).
### Add the logo in `gitlab-svgs`
All templates fetch their icons from the
[`gitlab-svgs`](https://gitlab.com/gitlab-org/gitlab-svgs) library, so if the
icon of the template you add is not present, you have to submit one.
See how to add a [third-party logo](https://gitlab.com/gitlab-org/gitlab-svgs/-/tree/main#adding-third-party-logos-or-trademarks).
After the logo is added to the `main` branch,
[the bot](https://gitlab.com/gitlab-org/frontend/renovate-gitlab-bot/) picks the
new release up and create an MR in `gitlab-org/gitlab`. You can now proceed to
the next step.
### Add the template details
Two types of built-in templates are available in GitLab:
- **Standard templates**: Available in all GitLab tiers.
- **Enterprise templates**: Available only in GitLab Premium and Ultimate.
To make the project template available when creating a new project, you must
follow the vendoring process to create a working template.
#### Standard template
NOTE:
See merge request [25318](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) for an example.
To contribute a standard template:
1. Add the details of the template in the `localized_templates_table` method in [`lib/gitlab/project_template.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/project_template.rb) using the following scheme:
```ruby
ProjectTemplate.new('<template_name>', '<template_short_description>', _('<template_long_description>'), '<template_project_link>', 'illustrations/logos/<template_logo_name>.svg'),
```
1. Add the details of the template in [`app/assets/javascripts/projects/default_project_templates.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/projects/default_project_templates.js).
1. Add the template name to [`spec/support/helpers/project_template_test_helper.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/project_template_test_helper.rb).
#### Enterprise template
NOTE:
See merge request [28187](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28187) for an example.
To contribute an Enterprise template:
1. Add details of the template in the `localized_ee_templates_table` method in [`ee/lib/ee/gitlab/project_template.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/project_template.rb) using the following scheme:
```ruby
ProjectTemplate.new('<template_name>', '<template_short_description>', _('<template_long_description>'), '<template_project_link>', 'illustrations/logos/<template_logo_name>.svg'),
```
1. Add the template name in the list of `let(:enterprise_templates)` in [`ee/spec/lib/gitlab/project_template_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/lib/gitlab/project_template_spec.rb).
1. Add details of the template in [`ee/app/assets/javascripts/projects/default_project_templates.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/assets/javascripts/projects/default_project_templates.js).
### Populate the template details
1. Start GDK:
```shell
gdk start
```
1. Run the following in the `gitlab` project, where `<template_name>` is the name you
gave the template in `gitlab/project_template.rb`:
```shell
bin/rake "gitlab:update_project_templates[<template_name>]"
```
1. Regenerate the localization file in the `gitlab` project and commit the new `.pot` file:
```shell
bin/rake gettext:regenerate
```
1. Add a changelog entry in the commit message (for example, `Changelog: added`).
For more information, see [Changelog entries](changelog.md).
## Update an existing built-in project template
To contribute a change:
1. Open a merge request in the relevant project, and leave the following comment
when you are ready for a review:
```plaintext
@gitlab-org/manage/import/backend this is a contribution to update the project
template and is ready for review!
@gitlab-bot ready
```
1. If your merge request gets accepted:
- Either [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new)
to ask for it to get updated.
- Or update the vendored template and open a merge request:
```shell
bin/rake "gitlab:update_project_templates[<template_name>]"
```
## Test your built-in project with the GitLab Development Kit
Complete the following steps to test the project template in your own
GDK instance:
1. Start GDK:
```shell
gdk start
```
1. Run the following Rake task, where `<template_name>` is the
name of the template in `lib/gitlab/project_template.rb`:
```shell
bin/rake "gitlab:update_project_templates[<template_name>]"
```
1. Visit GitLab in your browser and create a new project by selecting the
project template.
## For GitLab team members
Ensure all merge requests have been reviewed by the Security counterpart before merging.
### Update all templates
Starting a project from a template needs this project to be exported. On a
up to date default branch run:
```shell
gdk start # postgres, praefect, and sshd are required
bin/rake gitlab:update_project_templates
git checkout -b update-project-templates
git add vendor/project_templates
git commit
git push -u origin update-project-templates
```
Now create a merge request and assign to a Security counterpart to merge.
### Update a single template
To update just a single template instead of all of them, specify the template name
between square brackets. For example, for the `jekyll` template, run:
```shell
bin/rake "gitlab:update_project_templates[jekyll]"
```
### Review a template merge request
To review a merge request which changes one or more vendored project templates,
run the `check-template-changes` script:
```shell
scripts/check-template-changes vendor/project_templates/<template_name>.tar.gz
```
This script outputs a diff of the file changes against the default branch and also verifies that
the template repository matches the source template project.
|
