README.md 6.12 KB
Newer Older
1 2 3 4 5
Music is the new GNOME music playing application.

# Where can I find more?

Music has a wiki page at
Marinus Schraal's avatar
Marinus Schraal committed
6
https://wiki.gnome.org/Apps/Music.
7 8 9 10 11

You can join the developers on IRC: [#gnome-music](irc://irc.gnome.org/gnome-music) on [GIMPNet](https://wiki.gnome.org/Community/GettingInTouch/IRC).

# Join the development

Marinus Schraal's avatar
Marinus Schraal committed
12
Follow the [GNOME Newcomers guide](https://wiki.gnome.org/Newcomers/) and choose Music as your project. There are bugs labeled for newcomers, which should provide an easy entry point. Of course, feel free to pick something more challenging. Pick bugs if you can, not feature requests. The goal is to make the current Music experience sound & stable and only then extend it's functionality.
13

14 15
### Build Music

16
Music uses the [meson](http://mesonbuild.com/) build system. Use the following commands to build Music from the source directory:
17

18 19 20 21
```sh
$ meson _build
$ cd _build
$ ninja
22
```
23 24 25 26 27

Then you can either run in the build dir by running:

```sh
$ ./local-music
28 29
```

30 31 32 33 34
You can also install Music system-wide by running:

```sh
$ ninja install
```
35

Marinus Schraal's avatar
Marinus Schraal committed
36
## Coding style
37 38 39 40 41 42 43 44 45 46

GNOME Music is written in Python and aspires to adhere to the coding style described in the python style guide [PEP-8](https://www.python.org/dev/peps/pep-0008/).

Since Music was written over many years and by many different contributors without a single style being enforced, it currently is in a mixed style state. The goal is to eventually consistently follow  [PEP-8](https://www.python.org/dev/peps/pep-0008/) for style and [PEP-257](https://www.python.org/dev/peps/pep-0257/) for docstrings. The content of docstrings uses the [Sphinx markup style](http://www.sphinx-doc.org/).

Docstrings should be added to all (new) public functions.

Since looking at the surrounding code might give mixed results, take note of the following rules as a basic style guide.

### Line length
Marinus Schraal's avatar
Marinus Schraal committed
47

48 49 50 51 52 53 54 55 56
>>>
Limit all lines to a maximum of 79 characters.

For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters.
>>>

### Indentation

Music uses hanging indents when the lines get too long.
Marinus Schraal's avatar
Marinus Schraal committed
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
>>>
When using a hanging indent the following should be considered; there should be no arguments on the first line and further indentation should be used to clearly distinguish itself as a continuation line.
>>>

```python
# More indentation included to distinguish this from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
```

### Line break before a binary operator

```python
# Yes: easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()
```

### Class internals

All non-public classwide variables or methods should be prepended with an underscore.
>>>
_single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects whose name starts with an underscore.
>>>

Marinus Schraal's avatar
Marinus Schraal committed
98 99 100 101 102
### PyGObject specifics

#### Treemodel

Use PyGObject shorthands for manipulating `GtkTreeModel` & `GtkListStore`:
103 104 105 106 107

```python
model[iter][0] = "artist"
artist, title = model[iter][1, 4]
```
Marinus Schraal's avatar
Marinus Schraal committed
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

#### Properties

Most objects in Music are derived from GObject and have properties. Use [PyGObject properties](https://pygobject.readthedocs.io/en/latest/guide/api/properties.html) through decorator usage if you add properties to your code.

Short form for simple properties:

```python
selected = GObject.Property(type=bool, default=False)
```

With method definition if more control is needed:

```python
@GObject.Property(type=bool, default=False)
def selection_mode(self):
    return self._selection_mode

@selection_mode.setter
def selection_mode(self, value):
    self._selection_mode = value
```

Manipulate and refer to GObject properties with the *props* attribute to set them apart from regular python attributes:

```python
is_selected = object.props.selected

object.props.selection_mode = True
```

##### Multi-word properties

Note that GObject multi-word properties are separated by `-` as in `'selection-mode'`, however Python does not allow `-` in variable or method names. So these are translated to `_` instead. You might find both `'selection-mode'` and `selection_mode` in the code (depending on how they are used), but they refer to the same property.

#### Templates

Recent PyGObject (3.29.1 and up) allows template usage and Music is [starting to convert](https://gitlab.gnome.org/GNOME/gnome-music/issues/183) to using this to build the user interface. More information can be found in the PyGObject source and [examples](https://gitlab.gnome.org/GNOME/gnome-music/blob/master/gnomemusic/widgets/songwidget.py) in the Music code.

The basic usage in Python is as follows, with the `widget.ui` file being a regular GTK template:

```python
@Gtk.Template(resource_path='/org/gnome/Music/widget.ui')
class Widget(Gtk.Widget):

    __gtype_name__ = 'Widget'

    _button = Gtk.Template.Child()

    @Gtk.Template.Callback()
    def _on_button_clicked(self, klass):
        pass
```

## Commit messages

Music is fairly strict on the format and contents of commit messages. New contributors often struggle with this.

The GNOME wiki has a good [intro](https://wiki.gnome.org/Git/CommitMessages) on what a proper commit message is and this is a **must read** for first-time contributors.

It is always recommended to look at other Music commit messages as well to get an idea of what a good commit message is specific to Music.

It should look somewhat like:

>>>
tag: Short explanation

Problem in some detail.
Implemented fix.

Closes: #issuenr
179 180 181 182 183
>>>

## Merge requests

When opening a Merge Request, please enable the [_'Allow commits from members who can merge to the target branch'_](https://docs.gitlab.com/ee/user/project/merge_requests/allow_collaboration.html) checkbox. This allows the Music maintainers to help out on the Merge Request as needed.