Skip to content

Latest commit

 

History

History
152 lines (99 loc) · 8.78 KB

CONTRIBUTING.md

File metadata and controls

152 lines (99 loc) · 8.78 KB
Raw

Ensembles Contributing Guide

Thank you for investing your time in contributing to Ensembles 🎉


Ensembles is Free and Opensource software and we welcome contributions and assistance. You can contribute in many ways, you can submit bug reports, feature requests or write code which goes into Ensembles. You can also contribute sounds for the default soundfont* or expand the roster of built-in Styles**. You can also propose changes to this document.

All members of our community are expected to follow our Code of Conduct to keep the community approchable and respectable.

In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.

Table of contents

New contributor guide

See the README to get an overview of the project. Here are some helpful resources to get you comfortable with open source contribution:

Unsure where to begin contributing to Ensembles? You can start by looking through the help-wanted or good first issue issues:

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

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. There is usually an easy way to rebase from within the pull request page directly.

Getting started

  • Ensembles is written in Vala and C languages

  • To start learning how to program in Vala, check out the official tutorial

  • To start learning how to program in C, check out the C programming tutorial

  • If you want to contribute in the musical content in Ensembles, you are free to use any software or DAW (so long as it fits their terms of use).

    1. The SoundFont is made using samples derived from sounds in the public domain or other soundfonts that are also in public domain. You can use Polyphone to modify it. To start learning on how to contribute sounds, check out Polyphone Documentation. You can add your name in the Copyright list in the General tab.

    2. The Style (Auto-accompaniment style) is basically a special kind of MIDI file. You can use RoseGarden to create Styles. Be sure to follow the Style Specification document, otherwise Ensembles won't recognize your Style file or run into errors and crashes. You can use any other DAW to make the Styles, so long as the Style file is as per specification.

  • To follow up on general questions about development in GTK, head over to Gnome Wiki

  • Ensembles App is hosted at Github. The soundfont is hosted at GitLab via GitLFS.

  • Development happens in the master branch, thus all Pull Request should be opened against the master branch.

  • Installing the app and soundfont

    You can install Ensembles by compiling it from source

    1. Install the required dependencies:

      • elementary-sdk
      • gtk+-3.0>=3.18
      • granite>=5.3.0
      • glib-2.0
      • gobject-2.0
      • meson
      • libhandy-1
      • fluidsynth>=2.2.1
      • portmidi

    2. Clone the app repository and change directory

      git clone https://github.com/SubhadeepJasu/ensembles.git
cd ensembles

    3. Building:

      meson _build --prefix=/usr
sudo ninja -C _build install

    4. Clone the SoundFont repository and change directory

      cd ..
git clone https://gitlab.com/SubhadeepJasu/ensemblesgmsoundfont.git
cd ensemblesgmsoundfont

    5. Installing SoundFont:

      meson _build --prefix=/usr
sudo ninja -C _build install

It is important to install the Ensembles GM SoundFont as well otherwise Ensembles won't make a sound (and may internally scream in pain)

Reporting bugs and issues

Security vulnerability

If you find a security vulnerability, do NOT open an issue. Email subhajasu@gmail.com instead.

  • Can I access something that's not mine, or something I shouldn't have access to?
  • Can I interfere with other Apps or Devices connected to the PC via Ensembles in ways that I am not supposed to? Can any other App or Device interfere with Ensembles in ways it's not supposed to?
  • Can I disable something for other people? If the answer to any of those three questions is "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to all questions, you may still be dealing with a security issue, so if you're unsure, just email us at subhajasu@gmail.com.

Bugs/Issues

If you have found a bug, first of all, make sure you are using the latest version of Ensembles (latest commit on master branch) - your issue may already have been fixed. If not, search our issues list on GitHub in case a similar issue has already been opened.

If you spot a problem with the docs, search if an issue already exists

If the issue has not been reported before, simply create a new issue via the Issues section

It is very helpful if you can prepare a reproduction of the bug. In other words, provide all the steps as well as a GIF or link to a video demonstrating the bug. It makes it easier to find the problem and to fix it.

Please adhere to the issue template and make sure you have provided as much information as possible. This helps the maintainers in resolving these issues considerably.

Please be careful of publishing sensitive information you don't want other people to see, or images whose copyright does not allow redistribution; the bug tracker is a public resource and attachments are visible to everyone.

Feature requests

If you find yourself wishing for a feature that doesn't exist in Ensembles, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that Ensembles has today have been added because our users saw the need.

To request a feature, open an issue on our issues list on GitHub which describes the feature you would like to see, why you need it, and how it should work.

Ensembles is maintained mainly by me and other contributors like you.

Pull requests

For something that is bigger than a one or two line fix:

  1. Create your own fork of the code
  2. Create a branch
  3. Commit your changes in the new branch
  4. If you like the change and think the project could use it:
    • Be sure you have followed the code style for the project.
    • Open a pull request with a good description (including issue number)

Review process

Pull Requests are looked at on a regular basis and they are dealt with on case by case basis and roadmap in mind.