CONTRIBUTING.md 3.71 KB
Newer Older
1
## Contributing to GNOME Podcasts
Jordan Petridis's avatar
Jordan Petridis committed
2 3

Thank you for looking in this file!
4

5
When contributing to the development of GNOME Podcasts, please first discuss the change you wish to make via issue, email, or any other method with the maintainers before making a change.
6

7
If you have any questions regarding the use or development of GNOME Podcasts,
Jordan Petridis's avatar
Jordan Petridis committed
8 9 10 11 12 13
want to discuss design or simply hang out, please join us in [#hammond on irc.gnome.org.](irc://irc.gnome.org/#hammond)

Please note we have a [code of conduct](https://wiki.gnome.org/Foundation/CodeOfConduc), please follow it in all your interactions with the project.

## Source repository

14
GNOME Podcasts's main source repository is at gitlab.gnome.org.  You can view
Jordan Petridis's avatar
Jordan Petridis committed
15
the web interface [here](https://gitlab.gnome.org/World/podcasts)
Jordan Petridis's avatar
Jordan Petridis committed
16 17 18 19 20 21 22 23

Development happens in the master branch.

Note that we don't do bug tracking in the Github mirror.

If you need to publish a branch, feel free to do it at any
publically-accessible Git hosting service, although gitlab.gnome.org
makes things easier for the maintainers.
24

25 26
## Style

Jordan Petridis's avatar
Jordan Petridis committed
27
We use [rustfmt](https://github.com/rust-lang-nursery/rustfmt) for code formatting and we enforce it on the gitlab-CI server.
28 29

Quick setup
Jordan Petridis's avatar
Jordan Petridis committed
30 31 32 33
```
cargo install rustfmt-nightly
cargo fmt --all
 ```
34

Jordan Petridis's avatar
Jordan Petridis committed
35 36 37 38 39 40
It is recommended to add a pre-commit hook to run cargo test and `cargo fmt`.
Don't forget to `git add` again after `cargo fmt`.
```
#!/bin/sh
cargo test -- --test-threads=1 && cargo fmt --all -- --write-mode=diff
```
41

42 43
## Running the test suite

44 45
Running the tests requires an internet connection and it it will download some files from the [Internet Archive](archive.org)

Jordan Petridis's avatar
Jordan Petridis committed
46 47
The test suite sets a temporary sqlite database in the `/tmp` folder.
Due to that it's not possible to run them in parrallel.
48 49 50

In order to run the test suite use the following: `cargo test -- --test-threads=1`

51 52
# Issues, issues and more issues!

53
There are many ways you can contribute to GNOME Podcasts, and all of them involve creating issues
Jordan Petridis's avatar
Jordan Petridis committed
54
in [GNOME Podcasts issue tracker](https://gitlab.gnome.org/World/podcasts/issues). This is the entry point for your contribution.
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76

To create an effective and high quality ticket, try to put the following information on your
ticket:

 1. A detailed description of the issue or feature request
     - For issues, please add the necessary steps to reproduce the issue.
     - For feature requests, add a detailed description of your proposal.
 2. A checklist of Development tasks
 3. A checklist of Design tasks
 4. A checklist of QA tasks

## Issue template
```
[Title of the issue or feature request]

Detailed description of the issue. Put as much information as you can, potentially
with images showing the issue or mockups of the proposed feature.

If it's an issue, add the steps to reproduce like this:

Steps to reproduce:

77
1. Open GNOME Podcasts
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
2. Do an Action
3. ...

## Design Tasks

* [ ]  design tasks

## Development Tasks

* [ ]  development tasks

## QA Tasks

* [ ]  qa (quality assurance) tasks
```

94 95 96
## Pull Request Process

1. Ensure your code compiles. Run `make` before creating the pull request.
97 98 99 100
2. Ensure the test suit passes. Run `cargo test -- --test-threads=1`.
3. Ensure your code is properly formated. Run `cargo fmt --all`.
4. If you're adding new API, it must be properly documented.
5. The commit message is formatted as follows:
101 102 103 104 105 106 107 108 109
   ```
   component: <summary>

   A paragraph explaining the problem and its context.

   Another one explaining how you solved that.

   <link to the bug ticket>
   ```
110
6. You may merge the pull request in once you have the sign-off of the maintainers, or if you
111 112 113 114
   do not have permission to do that, you may request the second reviewer to merge it for you.

## Code of Conduct
We follow the Gnome [Code of Conduct.](https://wiki.gnome.org/Foundation/CodeOfConduct)