Skip to content

This repository holds all the past and current proposals for the Mixxx Software

License

Notifications You must be signed in to change notification settings

mixxxdj/proposals

Repository files navigation

Proposals

This repository holds all the past and current proposals for the Mixxx Software. It’s the single place for reviewing, discovering, and working on the design documents. It is also a record of past decisions and approvals.

Current Proposals

What’s a Design Document?

It’s essential to clearly explain the reasons behind certain design decisions to have a community consensus. This is especially important in Mixxx, where every decision might have a significant impact given the high adoption and stability of the software and standards we work on.

In our world, no decision is perfect, so having a design document explaining our trade-offs is essential. Such a document can also be used later as a reference and for knowledge-sharing purposes.

Design documents do not always reflect what has been (or will be) implemented. Implementation details might have changed since a feature was merged. Design docs are not considered documentation and can not define a standard. Instead, it should explain the motivation, scope, decisions, and alternatives considered.

A design document shall describe the use-cases the proposal will implement and also the use-cases that are explicitly not included.

It may also contain requirements and acceptance criteria of a derived Pull Request. This avoid feature creep and adjust the expectations during a review.

Proposal Process

Don’t get scared to propose ideas! It’s amazing to innovate in the open and get feedback on ideas.

The process of proposing a change via a design document is the following:

  1. Fork github.com/mixxxdj/proposals.
  2. Create a GitHub Pull Request with a design document in markdown format to the proposals directory. Make sure to use the template as the guide for what sections should be present in the document. Put the creation date (the day you started preparing this design document) as the prefix and some unique name as the suffix in the file name. Once the PR is proposed, a maintainer will assign a proposal label.
  3. An automatic formatter is enabled in the repository. Use pre-commit locally to trigger the formatting of all markdown documents (requires a working pre-commit installation).
  4. After a sufficient amount of discussion, the Mixxx team will try to reach a consensus of accepting or rejecting the proposal. In the former case, the PR gets merged. In the latter case, the PR gets closed with meaningful reasons why the proposal was rejected.
    1. To merge the PR, we need approval (consensus) from the maintainers of the related component(s).
    2. Optionally: Find a sponsor among the Mixxx maintainers to get momentum on a change. You may use Zulip to do that.

Once the PR gets merged, the design document can change, but it requires (less strict, but still) a PR with review and merge by a maintainer.

Credits

This proposal process was largely inspired by the Prometheus Proposal Process

About

This repository holds all the past and current proposals for the Mixxx Software

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published