Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (139 loc) · 7.61 KB

CONTRIBUTING.md

File metadata and controls

197 lines (139 loc) · 7.61 KB

Contributing guide

Want to contribute? Great!

All contributions are more than welcome ! This includes bug reports, bug fixes, enhancements, features, questions, ideas, and documentation.

This document will hopefully help you contribute to hrmp.

Legal

All contributions to hrmp are licensed under the GPL v3 license

Reporting an issue

This project uses GitHub issues to manage the issues. Open an issue directly in GitHub.

If you believe you found a bug, and it's likely possible, please indicate a way to reproduce it, what you are seeing and what you would expect to see. Don't forget to indicate your hrmp version.

Setup your build environment

For Red Hat RPM based distributions use the following command:

dnf install git gcc clang clang-analyzer clang-tools-extra cmake make python3-docutils libasan libasan-static alsa-lib alsa-lib-devel libsndfile libsndfile-devel opus opus-devel faad2-libs faad2-devel gtk3 gtk3-devel

in order to get the necessary dependencies.

Building the main branch

To build the main branch:

git clone https://github.com/HighResMusicPlayer/hrmp.git
cd hrmp
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make
cd src
./hrmp -?

Before you contribute

To contribute, use GitHub Pull Requests, from your own fork.

Also, make sure you have set up your Git authorship correctly:

git config --global user.name "Your Full Name"
git config --global user.email your.email@example.com

We use this information to acknowledge your contributions in release announcements.

Code reviews

GitHub pull requests can be reviewed by all such that input can be given to the author(s).

See GitHub Pull Request Review Process for more information.

Coding Guidelines

  • Discuss the feature
  • Do development
    • Follow the code style - use the clang-format.sh script
  • Commits should be atomic and semantic. Therefore, squash your pull request before submission and keep it rebased until merged
    • If your feature has independent parts submit those as separate pull requests

Discuss a Feature

You can discuss bug reports, enhancements and features in our forum.

Once there is an agreement on the development plan you can open an issue that will used for reference in the pull request.

Development

You can follow this workflow for your development.

Add your repository

git clone git@github.com:yourname/hrmp.git
cd hrmp
git remote add upstream https://github.com/HighResMusicPlayer/hrmp.git

Create a work branch

git checkout -b mywork main

During development

git commit -a -m "[#issue] My feature"
git push -f origin mywork

If you have more commits then squash them

git rebase -i HEAD~2
git push -f origin mywork

If the main branch changes then

git fetch upstream
git rebase -i upstream/main
git push -f origin mywork

as all pull requests should be squashed and rebased.

In your first pull request you need to add yourself to the AUTHORS file.

Policy and guidelines for using AI

Our goal in the hrmp project is to develop an excellent software system. This requires careful attention to detail in every change we integrate. Maintainer time and attention is very limited, so it's important that changes you ask us to review represent your best work.

You are encouraged to use tools that help you write good code, including AI tools. However, as noted above, you always need to understand and explain the changes you're proposing to make, whether or not you used an LLM as part of your process to produce them. The answer to “Why did you make change X?” should never be “I'm not sure. The AI did it.”

Do not submit an AI-generated PR you haven't personally understood and tested, as this wastes maintainers' time. PRs that appear to violate this guideline will be closed without review. Using AI as a coding assistant and help you create a skeleton for your code.

  • Don't skip becoming familiar with the part of the codebase you're working on. This will let you write better prompts and validate their output if you use an LLM. Code assistants can be a useful search engine/discovery tool in this process, but don't trust claims they make about how hrmp works. LLMs are often wrong, even about details that are clearly answered in the hrmp documentation and surrounding code
  • Don't simply ask an LLM to add code comments, as it will likely produce a bunch of text that unnecessarily explains what's already clear from the code. If using an LLM to generate comments, be really specific in your request, demand succinctness, and carefully edit the result.

Using AI for communication

As noted above, hrmp's contributors are expected to communicate with intention, to avoid wasting maintainer time with long, sloppy writing. We strongly prefer clear and concise communication about points that actually require discussion over long AI-generated comments.

When you use an LLM to write a message for you, it remains your responsibility to read through the whole thing and make sure that it makes sense to you and represents your ideas concisely. A good rule of thumb is that if you can't make yourself carefully read some LLM output that you generated, nobody else wants to read it either.

Here are some concrete guidelines for using LLMs as part of your communication workflows.

  • When writing a pull request description, do not include anything that's obvious from looking at your changes directly (e.g., files changed, functions updated, etc.). Instead, focus on the why behind your changes. Don't ask an LLM to generate a PR description on your behalf based on your code changes, as it will simply regurgitate the information that's already there.
  • Similarly, when responding to a pull request comment, explain your reasoning. Don't prompt an LLM to re-describe what can already be seen from the code.
  • Verify that everything you write is accurate, whether or not an LLM generated any part of it. hrmp's maintainers will be unable to review your contributions if you misrepresent your work (e.g., misdescribing your code changes, their effect, or your testing process).
  • Complete all parts of the PR description template, maybe with screenshots and the self-review checklist. Don't simply overwrite the template with LLM output.
  • Clarity and succinctness are much more important than perfect grammar, so you shouldn't feel obliged to pass your writing through an LLM. If you do ask an LLM to clean up your writing style, be sure it does not make it longer in the process. Demand succinctness in your prompt.
  • Quoting an LLM answer is usually less helpful than linking to relevant primary sources, like source code, reference documentation, or web standards. If you do need to quote an LLM answer in a hrmp conversation, put the answer in a hrmp quote block, to distinguish LLM output from your own thoughts.

Code Style

Please, follow the coding style of the project.

You can use the clang-format tool to help with the formatting, by running

./clang-format.sh

and verify the changes.