musescore / musescore/MuseScore

Reorganise developer documentation

Open
#25,703 1 comment 2 reactions 2 assignees View on GitHub

@shoogle is already working on this.

Since Dec 2, 2024.

dev documentation internal P1
Dominant language
C++
Stars
15.1k
Forks
3.3k
Avg merge
2d 2h
Merged PRs (30d)
91

Description

Problems:
  1. Only the most essential instructions have been ported to the GitHub Wiki, while some other things are still only described at https://musescore.org/en/handbook/developers-handbook.
  2. Although people could of course dive into the revision history of the GitHub Wiki, compilation instructions for older branches are lost forever whenever we update the Wiki to the latest state of affairs.
  3. In order to create proper distro-specific builds, people currently have to reverse-engineer our build scripts, because there are no docs. We discourage the use of 3rd-party builds, for the reason that these are sometimes created in the wrong way or with the wrong dependency versions and we don't want to be distracted by bugs arising from this; but we must acknowledge that people will create distro-specific builds anyway, because native packages simply provide better UX than whatever AppImage. So we should provide documentation how to properly create releasable builds.
Solutions/ideas:
  1. Keep essential build instructions inside the source code as .md files, while providing more elaborate contribution instructions for the current state of affairs in the Wiki

    • This way, every branch contains basic documentation to build that branch, so that no information is lost as we move on.

    • This basic documentation should be aimed at experienced developers, in the sense that it should only provide information that can not be found in public sources outside our repository. For example, it should contain:

      • which dependencies and which versions we use
      • that we use the standard cd build; cmake ..; cmake --build . stuff
      • that we additionally require cmake --install ., and that one must only ever attempt to run the executable from the install directory, not from the build directory; because this is unusual
      • which CMake options should be used for which purpose; here, we should describe which options are necessary to create a developer build, and which options for a distributable build, for 3rdparty package maintainers

      But it should not contain things like how to run CMake, or how to open the repo in Qt Creator, or how to do Git.

    • The Wiki on the other hand should contain everything a contributor needs to know. Since many of our contributors are only just starting their software development journey, it would be wise to provide a certain level of detail, like how to use CMake, how the build.cmake utility script can be used to automate some things during development, how to configure certain IDEs properly. Additionally, this is the place to describe the contribution process.

  2. Dismantle the developers handbook on MuseScore.org
    It looks like basically every page needs special treatment:

    • Some pages should be ported over to the Wiki, because they contain compilation/development/contribution instructions that are still relevant nowadays.
    • Some pages contain compilation instructions that are relevant for the 3.x branch only. These instructions should be summarised and archived in a .md file on the 3.x branch.
    • Some pages describe things around the contribution process that are not relevant anymore. Most of this information can be deleted because it has no historical value; pieces that do have historical value should be archived somehow.
    • Some pages, like the one about command line options, don't belong in the developer handbook but in the user handbook
    • There is a "blog" page from a few years ago; it feels hard to throw that away... but what can we do with it?
    • Plugin development documentation is hosted in the developers handbook; that should be moved to a new site, or rather consolidated on one site. But: documentation for older MuseScore versions must remain available! (but in such way that it cannot be confused with the latest documentation)
    • There are some pages about the codebase that might even be interesting for us
    • There are some reference pages like https://musescore.org/en/node/334701
    • There are some release notes pages there; those should be moved elsewhere
    • Some pages are basically a tutorial about some external tool, like Git workflow; we can get rid of that, because there are enough dedicated Git tutorials online. We can pick one and add a link to it, if we deem that necessary.
    • Some pages are just outdated in every way and have no historical value so can go.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.