Reorganise developer documentation

[cbjeukendrup]

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.

[shoogle]

Looks good! I think it's worth having a cut-down version of the Git Workflow on our Wiki though, just to emphasise key points like:

• Don't work on your master branch
• Rebase on upstream instead of merging
• Use separate commits for independent changes
• Squash everything else

We could detect some of these mistakes in the codestyle check and use the error message to direct people to the relevant documentation.

I'd also like to mention how to perform common tasks in GitHub Desktop because there's at least one member of the internal team who prefers it to the command line, so it's good if the rest of us have this knowledge too, or at least know where to find it.