CONTRIBUTING.md 8.67 KB
Newer Older
1
# Contributing
Francesc Guasch's avatar
Francesc Guasch committed
2
3
4
5

First off, thank you for considering contributing to Ravada. It's people
like you that make it such a great tool.

6
## 1. Where do I go from here?
Francesc Guasch's avatar
Francesc Guasch committed
7
8
9
10
11
12

If you've noticed a bug or have a question that doesn't belong on the
[mailing list](http://groups.google.com/group/ravada)
or
[search the issue tracker](https://github.com/UPC/ravada/issues?q=something)
to see if someone else in the community has already created a ticket.
13
14
You can also ask in our [telegram public group](https://t.me/ravadavdi).
If it is not, go ahead and [create a new issue](https://github.com/UPC/ravada/issues/new)!
Francesc Guasch's avatar
Francesc Guasch committed
15

Francesc Guasch's avatar
Francesc Guasch committed
16
17
18
19
20
21
22
23
24
25
26
27
## 2. Source code

We manage the code with Git. If you already know it, skip this point. If this is the
first time you work with it, beware it has a learning curve. First of all read some
introduction. Then please ask questions if you need it, we are more than willing to
mentor first timers.

* Join the [Ravada Google group](https://groups.google.com/forum/#!forum/ravada).
* Meet us in our [Telegram public group](http://t.me/ravadavdi).


## 3. Fork & create a branch
Francesc Guasch's avatar
Francesc Guasch committed
28
29

If this is something you think you can fix, then
Francesc Guasch's avatar
Francesc Guasch committed
30
[fork Ravada](https://help.github.com/articles/fork-a-repo)
Francesc Guasch's avatar
Francesc Guasch committed
31

Francesc Guasch's avatar
Francesc Guasch committed
32
## 4. Code Style
Francesc Guasch's avatar
Francesc Guasch committed
33

34
35
36
37
38
39
40
See our
[editor configuration](http://ravada.readthedocs.io/en/latest/devel-docs/editor-rules.html)
guidelines so your code gets along with old code. A recurrent problem for newcommers
is to submit code automatically cleaned by the editor. Usually, removed end of line
spaces or spaces converted to tabs.
Please make sure you don't do that. Run ``git diff`` before commit to see what you are
exactly contributing.
Francesc Guasch's avatar
Francesc Guasch committed
41

Francesc Guasch's avatar
Francesc Guasch committed
42
## 5. Commit Format
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

If you contribute code, *thank you* ! Plase, follow this guide.

Each commit message consists of a header, a body, and a footer. The header has a special format that includes a type, a scope, and a description.
We use [conventional commits](https://conventionalcommits.org/) format. Each commit must be for
a reason, and we should have an [issue](https://github.com/UPC/ravada/issues) for that, so we
decided to add the issue number in the footer.

The commit message should be structured as follows:

```
type(optional scope): description
<blank line>
optional body
<blank line>
footer #issue
```

Example:
```
63
fix(backend): active virtual machines can not be started
64
65
66
67
68
69
70
71

check the machine status before start
returns if machine active
before it crashed trying to start the machine

fixes #77
```

Francesc Guasch's avatar
Francesc Guasch committed
72
### 5.1 Header: Type
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

Commits must be prefixed with a type, which consists of a verb, feat, fix, build, followed by a colon and space.

Your options:

- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
- docs: Documentation only changes.
- feat: A new feature.
- fix: A bug fix.
- perf: A code change that improves performance.
- refactor: A code change that neither fixes a bug or adds a feature.
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
- test: Adding missing tests or correcting existing tests.

Francesc Guasch's avatar
Francesc Guasch committed
88
### 5.2 Header: Optional Scope
89
90
91
92
93

Refers to the extent, subject matter or contextual information about your changes. A scope is a phrase describing the file modified or a section of the codebase, it is always enclosed in parenthesis.

Example for a (optional scope):

Francesc Guasch's avatar
Francesc Guasch committed
94
    feat(parser): add ability to parse arrays
95

Francesc Guasch's avatar
Francesc Guasch committed
96
### 5.3 Header: Description
97
98
99
100
101
102
103
104
105
106
107

A description must immediately follow the type(optional scope): The description is a short description of the commit.

Important:

 - About commit character length, keep it concise and don't write more than 50 characters.
 - Use the imperative present tense: change, make, add, update, fix, etc; Do not use changed,
    changes, added, fixes, fixed, etc.
 - Don't capitalize the first letter.
 - Do not use a dot (.) at the end.

Francesc Guasch's avatar
Francesc Guasch committed
108
### 5.4 Header Lenghth
109
110
111

The header cannot be longer than 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

Francesc Guasch's avatar
Francesc Guasch committed
112
### 5.5 Writing the optional body
113
114
115
116
117
118
119
120
121
122
123

The body should include the motivation for the change and contrast this with previous behavior.

Example for optional body:

```
fix orthography
remove out of date paragraph
fix broken links
 ```

Francesc Guasch's avatar
Francesc Guasch committed
124
### 5.6 Writing the optional footer
125
126
127
128
129
130
131
132

The <optional footer> should contain a closing reference to an issue if any.

For example, to close an issue numbered 123, you could use the phrases Closes #123 in your
pull request description or commit message. Once the branch is merged into the default branch,
the issue will close.


Francesc Guasch's avatar
Francesc Guasch committed
133
## 6. Get the tests running
Francesc Guasch's avatar
Francesc Guasch committed
134
135
136

See this documentation about [testing](http://ravada.readthedocs.io/en/latest/devel-docs/commit-rules.html#testing) the project.

Francesc Guasch's avatar
Francesc Guasch committed
137
## 7. Did you find a bug?
Francesc Guasch's avatar
Francesc Guasch committed
138
139
140
141
142
143
144

* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/UPC/ravada/issues).

* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/UPC/ravada/issues/new).
Be sure to include a **title and clear description**, as much relevant information as possible,
and a **code sample**, an **executable test case** or a step by step guide demonstrating the expected behavior that is not occurring.

Francesc Guasch's avatar
Francesc Guasch committed
145
## 8. Implement your fix or feature
Francesc Guasch's avatar
Francesc Guasch committed
146
147
148
149

At this point, you're ready to make your changes! Feel free to ask for help;
everyone is a beginner at first :smile_cat:

Francesc Guasch's avatar
Francesc Guasch committed
150
Follow this guide about running [Ravada in development mode](http://ravada.readthedocs.io/en/latest/devel-docs/run.html).
Francesc Guasch's avatar
Francesc Guasch committed
151

Francesc Guasch's avatar
Francesc Guasch committed
152
153
If you change a translation or language file make sure you follow this small [guide](http://ravada.readthedocs.io/en/latest/devel-docs/translations.html?highlight=translate) and don't forget to add the issue number when committing.

Francesc Guasch's avatar
Francesc Guasch committed
154
## 9. Push your changes
155
156
157
158
159
160
161
162

Pushing refers to sending your committed changes to a remote repository, such as a repository
hosted on GitHub. Before that all the changes where local in the computer you are working in.

After working on your changes you need to Push it (upload) your newly created branch to GitHub

    git push

Francesc Guasch's avatar
Francesc Guasch committed
163
## 10. Create a Pull Request
Francesc Guasch's avatar
Francesc Guasch committed
164

165
166
Pull requests or PR are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators.

Francesc Guasch's avatar
Francesc Guasch committed
167

168
Send your changes to github *pushing* them up:
Francesc Guasch's avatar
Francesc Guasch committed
169
170

```sh
171
git push
Francesc Guasch's avatar
Francesc Guasch committed
172
173
```

174
175
Finally, go to your GitHub repository and
[create a Pull Request](https://github.com/pulls)
176

Francesc Guasch's avatar
Francesc Guasch committed
177
### 10.1 How to Write a Title for a Pull Request
178
179
180
181
182
183

Pull Request should be named in reference to the main fix or feature you provide; minor information can be added to the description. Please be specific and don't use generic terms.
Keep it concise and don't write more than 50 characters in the title.

Read [more information about PR](https://help.github.com/articles/creating-a-pull-request)

Francesc Guasch's avatar
Francesc Guasch committed
184

Francesc Guasch's avatar
Francesc Guasch committed
185
### 10.2 Keeping your Pull Request updated
Francesc Guasch's avatar
Francesc Guasch committed
186
187
188
189
190
191
192
193
194
195

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code
has changed, and that you need to update your branch so it's easier to merge.

To learn more about rebasing in Git, there are a lot of
[good](http://git-scm.com/book/en/Git-Branching-Rebasing)
[resources](https://help.github.com/articles/interactive-rebase),
but here's the suggested workflow:

```sh
196
git remote add upstream https://github.com/UPC/ravada.git
197
198
git fetch upstream
git rebase upstream/develop
Francesc Guasch's avatar
Francesc Guasch committed
199
200
```

Francesc Guasch's avatar
Francesc Guasch committed
201
### 10.3 Merging a PR (maintainers only)
Francesc Guasch's avatar
Francesc Guasch committed
202
203
204
205
206
207
208
209
210
211

A PR can only be merged into master by a maintainer if:

* It is passing CI.
* It has been approved by at least one admin.
* It has no requested changes.
* It is up to date with current master.

Any maintainer is allowed to merge a PR if all of these conditions are
met.
212

213
214
215
216
217
218
219
## 11 Reset my fork to upstream

You may want to ditch everything in your fork

### 11.1 Reset develop branch

 If you want to get even with main develop branch.
220
221
222
223
224
225
226
227
228

```sh
git remote add upstream https://github.com/UPC/ravada
git fetch upstream
git checkout develop
git reset --hard upstream/develop
git push origin develop --force
```

229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
### 11.2 Work in a new fresh branch

We create a new branch called *feature/cool_thing* and make it exactly like UPC/develop branch:

First we add the upstream remote source and fetch it. If you added this remote before you will get an error *fatal: remote upstream already exists.*. Don't worry and run the `git fetch upstream` anyway so it downloads the UPC source.

```sh
git remote add upstream https://github.com/UPC/ravada
git fetch upstream
```

Now we create a new branch:

```sh
git checkout -b feature/cool_thing
```

Reset this branch, now it will be an exact replica of upstream UPC/develop:

```sh
git reset --hard upstream/develop
git push --set-upstream origin feature/cool_thing
```

Now work on your code, test it so it is great. Then commit, push and create a *pull request*.