CONTRIBUTING.md 10.5 KB
Newer Older
1
2
3
4
5
6
## Contributing

Thank you for your interest in contributing to this GitLab project! We welcome
all contributions. By participating in this project, you agree to abide by the
[code of conduct](#code-of-conduct).

7
## Developer Certificate of Origin + License
8

9
10
11
12
13
14
15
16
17
By contributing to GitLab B.V., You accept and agree to the following terms and
conditions for Your present and future Contributions submitted to GitLab B.V.
Except for the license granted herein to GitLab B.V. and recipients of software
distributed by GitLab B.V., You reserve all right, title, and interest in and to
Your Contributions. All Contributions are subject to the following DCO + License
terms.

[DCO + License](https://gitlab.com/gitlab-org/dco/blob/master/README.md)

18
19
20
21
All Documentation content that resides under the [doc/ directory](/doc) of this
repository is licensed under Creative Commons:
[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).

22
_This notice should stay as the first item in the CONTRIBUTING.md file._
23

24
25
## Definition of done

26
The omnibus-gitlab project uses the [definition of done as noted in GitLab Community Edition (and Enterprise Edition)](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/doc/development/contributing/merge_request_workflow.md#definition-of-done).
27
28
29
30
31
32
33

As this project is a wrapper around GitLab CE/EE, some additions to the definition apply:

1. Integration tests using [GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa).
1. Green pipelines in both [gitlab.com pipelines](https://gitlab.com/gitlab-org/omnibus-gitlab/pipelines) (Specs) and
[dev.gitlab.org pipelines](https://dev.gitlab.org/gitlab/omnibus-gitlab/pipelines) (Package builds). This rule is at minimum applicable to the reviewers.

Jacob Vosmaer's avatar
Jacob Vosmaer committed
34

Balasankar C's avatar
Balasankar C committed
35
## General issue guidelines
36

37
38
If you are experiencing problems during GitLab package installation or have issues with package configuration please create an issue that includes the following:

Anastas Dancha's avatar
Anastas Dancha committed
39
- Include the omnibus-gitlab version when discussing behavior: `dpkg-query -W "gitlab*"` or `rpm -q gitlab`.
40
- Include the omnibus-gitlab configuration: `sudo gitlab-ctl show-config`
41
- Copy few lines before, full error output and few lines after from the `gitlab-ctl reconfigure` run log and paste it inside a [GitLab snippet](https://gitlab.com/snippets) or inside the issue description under triple backticks "``` TEXT ```".
42
43

*Warning* Be careful when pasting log outputs of `gitlab-ctl reconfigure` or `gitlab-ctl show-config`; They will contain secrets like passwords and keys so *make sure to edit out all secrets before pasting the log output*.
44

45
46
#### For problems not related to package installation and configuration check ways to get help [at GitLab website.](https://about.gitlab.com/getting-help/)

47
48
This can be the case when installation and `gitlab-ctl reconfigure` run went without issues but your GitLab instance is still giving 500 error page with an error in the log.

49
50
## I want to contribute!

51
If you want to contribute to GitLab Omnibus, issues with both the ~Accepting merge requests and ~For Scheduling labels
52
53
54
55
56
57
58
59
60
are issues that have been triaged as areas where where we are looking for contributors to help us out.

See the [contributor issue issues list](https://gitlab.com/gitlab-org/omnibus-gitlab/issues?state=opened&label_name[]=Accepting%20merge%20requests&label_name[]=For%20Scheduling).

If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to
learn how to communicate with GitLab. If you're looking for a Gitter or Slack channel
please consider we favor
[asynchronous communication](https://about.gitlab.com/handbook/communication/#internal-communication) over real time communication. Thanks for your contribution!

61
62
## Maintainer documentation

Ankita Singh's avatar
Ankita Singh committed
63
64
65
Maintainers of this project will try to address issues promptly.
Maintainers, however, cannot guarantee that they would be able to handle
all the incoming issues as soon as they are raised, nor can they guarantee to provide an
66
67
68
answer to all raised issues.

If your issue is closed due to inactivity (from either side), please check
Ankita Singh's avatar
Ankita Singh committed
69
70
whether the problem persists in the latest version. Feel free
to reopen the issue or create a new one linked to the old issue.
71

72
73
74
75
76
77
78
79
80
### Issue description templates

Issue description template will show this message to
all users that create issues in this repository:

```
When submitting an issue that is not a feature request, please submit the following:

1. Make sure that the issue is with the package itself. If your GitLab is running but you are seeing error page 500, first check https://about.gitlab.com/getting-help/ on where to ask your question
81
82
1. Include the omnibus-gitlab package version with: `dpkg-query -W
gitlab` or `rpm -q gitlab`
83
84
85
86
87
1. Relevant sections of `/etc/gitlab/gitlab.rb` (make sure to omit any sections that start with # and passwords)
1. Whether the problems are caused on a fresh install or an upgrade(Describe the upgrade history)
1. Describe the OS and the system environment GitLab is installed on (Is it a clean VM, is anything else running on it, etc.)
```

88
89
90
91
92
93
94
95
### Issue response template

When the maintainer suspects the reported issue is not related to the problems with omnibus-gitlab, following template can be used to respond to the issue reporter:

```
Thanks for reporting this issue. I suspect that the issue you are experiencing is not related to the package or configuration of the package itself. Omnibus-gitlab repository is used for packaging GitLab. Since this looks like a problem not related to the packaging please check
[how to get help](https://about.gitlab.com/getting-help/) for your issue. I will close this issue but if you still think this is a problem with the package please @ mention me with the steps to reproduce the problem and I will reopen the issue.
```
96
97
98
99
100
101
102
103
104
105
106
107
108

### Closing issues

If an issue has a `Awaiting Feedback` label and the response from the reporter
has not been received for 14 days, we can close the issue using the following
response template:

```
We haven't received an update for more than 14 days so we will assume that the
problem is fixed or is no longer valid. If you still experience the same problem
try upgrading to the latest version. If the issue persists, reopen this issue
with the relevant information.
```
Balasankar C's avatar
Balasankar C committed
109

110
111
112
113
114
115
116
117
118
119
120
### Hand testing built packages

Once you have a have a green pipeline for the package build as discussed in the
[Definition of done](#definition-of-done), deploy the package to a VM and ensure
that everything still works.

Some of the interactions of the components are not fully covered by the
unit/acceptance tests, so testing here can reveal issues such as invalid service
configuration being generated.  Issues found should be fed back into the test
suites where possible as part of the review process.

121
122
123
124
### Reviewing Merge Requests

Before merging, a MR must be reviewed by a [GitLab Omnibus Maintainer](https://about.gitlab.com/handbook/engineering/projects/#omnibus-gitlab).
If the change is not time-sensitive, then the MR can first be reviewed by any other
125
[Distribution Team Member](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#team-members),
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
then finally reviewed by a Maintainer.

Reviews generally only need the *approval* of one Maintainer to be merged, but
additional Maintainers may be involved with reviewing parts of the change. We will
try to avoid having more than one Maintainer do a full review.

**When the change was unscheduled, and requires notifying users**

The [Distribution Engineering Manager](https://about.gitlab.com/company/team/#maxlazio)
need to provide approval if the change is for an unscheduled issue, and makes a
user-facing change that needs mentioning in the release post.

**Other changes**

As long as one of the Maintainers is confident in the change, it does not need to
be reviewed again before merge.

143
> **Note**: This process is intended to balance code quality with effective use of reviewers' time. Just because a change was approved and merged by one Maintainer, does not guarantee that it won't be reverted later.
144

Balasankar C's avatar
Balasankar C committed
145
146
## Developer Guidelines

147
### Developer Documentation
Balasankar C's avatar
Balasankar C committed
148

149
See the [developer documentation](doc/development/README.md) for additional information.
Balasankar C's avatar
Balasankar C committed
150

151
#### Setting up development environment
152

153
See the [developer documentation](doc/development/README.md#setting-up-development-environment)
154

155
#### Understanding the architecture
Balasankar C's avatar
Balasankar C committed
156

157
See the [developer documentation](doc/development/README.md#understanding-the-architecture)
Balasankar C's avatar
Balasankar C committed
158

159
### Writing tests
Balasankar C's avatar
Balasankar C committed
160

161
See the [developer documentation](doc/development/README.md#writing tests)
162

163
### Merge Request Guidelines
164

165
See the [developer documentation](doc/development/README.md#merge-request-guidelines)
166

167
## Unofficial packaging point of contact
168
169
170
171
172
173

The omnibus-gitlab project is a project used for building official GitLab packages.
There are multiple community driven projects for packaging, such as [GitLab CE unofficial Debian 9](https://packages.debian.org/stretch/gitlab) package.

If you are a maintainer or point of contact for a such project, and you require
assistance or just want to talk about GitLab, please raise [an issue in the omnibus-gitlab project](https://gitlab.com/gitlab-org/omnibus-gitlab/issues).
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
200
201
202
203
204

## Code of conduct

As contributors and maintainers of this project, we pledge to respect all people
who contribute through reporting issues, posting feature requests, updating
documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free
experience for everyone, regardless of level of experience, gender, gender
identity and expression, sexual orientation, disability, personal appearance,
body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual
language or imagery, derogatory comments or personal attacks, trolling, public
or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct. Project maintainers who do not follow the
Code of Conduct may be removed from the project team.

This code of conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior can be
reported by emailing contact@gitlab.com.

This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant], version 1.1.0,
available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/).

[contributor-covenant]: http://contributor-covenant.org