docs/CONTRIBUTING.md

   1 # Contributing
   2
   3 Contributions are welcome, and they are greatly appreciated! Every little bit
   4 helps, and credit will always be given.
   5
   6
   7 ## Types of Contributions
   8
   9 You can contribute in many ways:
  10
  11
  12 ### Report Bugs
  13
  14 Report bugs at <https://github.com/jack-mixer/jack_mixer/issues>.
  15
  16 If you are reporting a bug, please include:
  17
  18 - Your operating system name and version.
  19 - The **jack_mixer** version (see the "About" dialog).
  20 - The Python version (`python --version`).
  21 - A description of what went wrong ("X doesn't work" is *not enough!*).
  22 - Detailed steps to reproduce the bug.
  23 - Any details about your local setup that might be helpful in troubleshooting.
  24
  25
  26 ### Fix Bugs or Implement Features and Enhancements
  27
  28 Look through the GitHub issues for for anything tagged with "bug", "feature
  29 request" or "enhancement" and if you think you can help out, leave a comment
  30 on the issue saying what you intend to work on and in which timeframe.
  31
  32
  33 ### Write Documentation
  34
  35 **jack_mixer** could definitely use more documentation, whether it is more
  36 detailed man pages or a real user guide, better docstrings or comments in the
  37 code, or even third-party tutorials, video or quick tips on social media.
  38
  39 If you want to help out with the documentation, please get in touch with the
  40 **jack_mixer** maintainers via the Github issue tracker, email or on IRC
  41 (see [README] for contact information)
  42
  43
  44 ### Add or Update Translations
  45
  46 We would like to translate the user interface of **jack_mixer** in as many
  47 languages as possible and keep existing translations as up-to-date and
  48 error-free as possible.
  49
  50 See the [Translations](#translations) section below.
  51
  52
  53 ### Submit Feedback
  54
  55 The best way to send feedback is to also file an issue at
  56 <https://github.com/jack-mixer/jack_mixer/issues>.
  57
  58 If you are proposing a feature:
  59
  60 - Give a short and poignant title to your feature request issue.
  61 - Explain in detail how it would work.
  62 - Keep the scope as narrow as possible, to make it easier to implement.
  63 - Remember that this is a volunteer-driven project, and that contributions are
  64   welcome :)
  65
  66
  67 ## Development
  68
  69
  70 ### Development Environment Setup and Workflow
  71
  72 Ready to work on **jack_mixer**? First you should set up your local
  73 development environment:
  74
  75 1. Fork the [jack-mixer/jack_mixer] repo on GitHub.
  76
  77 2. Clone your fork locally:
  78
  79         $ git clone git@github.com:your_name_here/jack_mixer.git
  80
  81 3. Install all build and run-time requirements listed in the [INSTALL] file and
  82    make sure you can configure and build the application with `meson` as
  83    described in the same document.
  84
  85 4. Install `flake8`, `isort` and `black` either via your distribution's
  86    package management or with `pip install`.
  87
  88 5. Create a branch for local development of your new feature or bugfix:
  89
  90         $ git checkout -b bugfix/what-does-this-fix
  91
  92    or:
  93
  94         $ git checkout -b feature/what-does-this-do
  95
  96    Now you're ready to make your changes, make sure you follow the
  97    [Coding Guidelines](#coding-guidelines) outlined below.
  98
  99 6. Commit your changes and push your branch to GitHub:
 100
 101         $ git add .
 102         $ git commit -m "Detailed description of your changes."
 103         $ git push -u origin name-of-your-bugfix-or-feature
 104
 105 7. Submit a pull request through the GitHub website.
 106
 107 Create a new branch for every new PR, starting from the `main` branch.
 108
 109
 110 ### Coding Guidelines
 111
 112
 113 #### Python Code
 114
 115 - Check all Python code with `flake8` and fix all warnings and errors or
 116   explicitly silence them (and be ready to explain why you did this when
 117   your changes are reviewed).
 118 - Format all Python code with `isort` and `black`.
 119 - Line-endings should should be Unix style (`\n`), not Windows style (`\r\n`).
 120 - Cython files should follow the same formatting rules as Python source code,
 121   where possible.
 122 - The Python code must work for all supported Python 3 versions
 123   (see `pyproject.toml`).
 124
 125
 126 #### C Code
 127
 128 - Opening brackets go on their own line:
 129 ```
 130     if (condition)
 131     {
 132         stuff;
 133     }
 134 ```
 135 - There should be a space between keywords and parenthesis for:
 136   `if`, `else`, `while`, `switch`, `catch`, `function`.
 137 - Function calls have no space before the parentheses.
 138 - No spaces are left inside the parentheses.
 139 - A space after each comma, but without space before.
 140 - All binary operators must have one space before and one after.
 141 - There should be no empty comments.
 142
 143 These conventions may change in the future and we may introduce auto-formatting
 144 of C code with `clang-format` at some point.
 145
 146
 147 ## Translations
 148
 149
 150 ### Adding a New Translation
 151
 152 1. Copy `data/local/jack_mixer.pot` to `data/locale/jack_mixer-<lang>.po`,
 153    where `<lang>` is the two-letter code for the language of the new
 154    translation.
 155 2. Edit `data/local/meson.build` and add a string element with the language
 156    code for the new translation to the `languages`
 157    [array](https://mesonbuild.com/Syntax.html#arrays) (keep it sorted
 158    alphabetically).
 159 3. Edit `jack-mixer-<lang>.po` and translate all messages (you only need to
 160    translate the messages for `argparse`, which are used in the command line
 161    help text).
 162 4. Run `./tools/compile-messages.py` to compile all `*.po` files to `*.mo`
 163    files.
 164 5. Build the application with `meson` and then run it from the root of the
 165    source directory using the `./tools/jack_mixer.sh` script and check your
 166    translations. Also use the `-h` command line option to check the translation
 167    of the usage help message.
 168 6. Add a `Comment` tag in the new language to the `data/jack_mixer.desktop`
 169    file.
 170 7. Commit the `jack-mixer-<lang>.po` file and your changes to the `.desktop`
 171    and `data/locale/meson.build` files to a new branch and make a Pull Request.
 172
 173
 174 ### Updating a Translation
 175
 176 When the timestamp listed in `data/local/jack_mixer.pot` is newer than a
 177 translation `.po` file, it may contain updated or new messages, which need to
 178 be translated.
 179
 180 Run the `./tools/merge-messages.py` script to update all `*.po` files
 181 and then edit the `.po` for the language translation you want to update. Use
 182 `git diff jack-mixer-<lang>.po` to check for new or updated messages.
 183
 184 When you have made your edits, check the new translations as described above
 185 and make a new Pull Request (only include the `.po` files, which you edited).
 186
 187
 188 [jack-mixer/jack_mixer]: https://github.com/jack-mixer/jack_mixer
 189 [INSTALL]: ../INSTALL.md
 190 [README]: ../README.md