Skip to main content

Contributing

Filing an Issue​

We always encourage users to report bugs as soon as they experience them. In order to keep everything organized here are some questions you should ask yourself before reporting:

Common mistakes​

  • Have you followed everything in the docs?
  • Is your Python virtual environment active?
  • Did you download the latest version of SoundScapeExplorer?
  • Have you checked the versions of python, node and pnpm?

General issues​

  • Are you using the latest version of SoundScapeExplorer?
  • Has this issue been reported already? Please check the list of open issues.

Advice​

If you're sure you've followed all instructions and haven't made any of the common mistakes listed above, here are some guidelines for creating an issue:

  • Is this an issue with SoundScapeExplorer itself, or an installation error, or are you looking for help with your configuration? The issue tracker is for SoundScapeExplorer issues only. Try Getting in touch.
  • When you ask a question, make sure it's not an XY problem.
  • Provide as much information as you possibly can. Copy and paste shell and browser console outputs (F12 or Ctrl+Shift+I to open it).
  • Issues are formatted by Markdown. If you paste code into your issue, it will probably end up appearing quite broken because it was interpreted as Markdown. Enclose blocks of code with three backticks (```) at the start and end to make it a nicely formatted code block.

In your issue, please​

  • List all operating system names and versions involved in the issue, as well as the version of SoundScapeExplorer, your Python version, your Node.js version, your pnpm version, and your browser name and version.
  • List any other software name/version you think may be related.
  • Link to any relevant files (such as .h5 storage file).
  • Include any error messages you see.
  • List steps to reproduce.

The more information you have, the better. Post as much as you can related to the issues to help us resolve it in a timely matter. If you have multiple issues, please file them as separate issues. This will help us sort them out efficiently.

Don't ask a question not related to the topic of the current issue, especially if it's on someone else's issue. This is known as thread hijacking. You should create a new issue, or ask on another discussion forum. To contact a specific developer, find their GitHub profile and look for their email address, or Twitter, etc.

Thanks!

Contribution Standards​

Don't be afraid to contribute to the development of SoundScapeExplorer! Even if you don't think you've contributed much, it's still greatly appreciated.

Please make sure you abide by these contribution standards so we can retain a high quality codebase and make it easy for everyone to understand and contribute to the code.

  • Follow all coding standards set by existing code in the repo. Using your own preferences over the established ones for the project just ends up making the code messy.
  • Use a commit message using our Commit Message Guidelines.
  • An explanation of what the commit's changes do in your commit message is extremely useful. It helps people to more quickly understand what your code is doing.
  • When you submit a pull request, be willing to accept criticism. We don't criticise to make you feel bad - we want you to know where you may have made a mistake and this helps you grow as a developer.

Commit Message Guidelines​

This specification is inspired by and supersedes the Angular Commit Message Guidelines.

We have very precise rules over how our Git commit messages must be formatted. This format leads to easier to read commit history.

Each commit message consists of a header, a body, and a footer.

<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and must conform to the Commit Message Header format.

The body is optional. When the body is present it must be at least 20 characters long and must conform to the Commit Message Body format.

The footer is optional. The Commit Message Footer format describes what the footer is used for and the structure it must have.

Commit Message Header​

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope: App|Bin|Examples|Front|Processing
  │
  └─⫸ Commit Type: docs|feat|fix|perf|refactor

The <type> and <summary> fields are mandatory, the (<scope>) field is optional.

Type​

Must be one of the following:

  • chore: Miscellaneous changes that will get ignored by release pipelines
  • 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 nor adds a feature
  • test: Adding missing tests or correcting existing tests

Scope​

The scope should be the name of the module affected (as perceived by the person reading the changelog generated from commit messages).

The following is the list of supported scopes:

  • App
  • Bin
  • Examples
  • Front
  • Processing

You can narrow the scope by domains using /.

For instance, Front/Worker or Processing/Storage.

Summary​

Use the summary field to provide a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • capitalize the first letter
  • no dot (.) at the end

Commit Message Body​

Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".

Explain the motivation for the change in the commit message body. This commit message should explain why you are making the change. You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.

The footer can contain information about breaking changes and deprecations and is also the place to reference GitHub issues, and other PRs that this commit closes or is related to. For example:

BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>

or

DEPRECATED: <what is deprecated>
<BLANK LINE>
<deprecation description + recommended update path>
<BLANK LINE>
<BLANK LINE>
Closes #<pr number>

Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.

Similarly, a Deprecation section should start with "DEPRECATED: " followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path.