Improve documentation on how to install from sources

[llucax]

It was brought up by @david-natingga-frequenz in a meeting that the instructions on how to set up a local development environment was not visible enough.

Some points being made in the meeting

(in no particular order)

• @david-natingga-frequenz suggested to separate this instruction in a different file and link to it in the README.md and CONTRIBUTING.md files.

• Some people expected this to be more visible in the README.md file.

• @tiyash-basu-frequenz pointed out that he expects a "build from the sources" in the README.

• @nhatcher-frequenz said it was unexpected to find these instructions in the CONTRIBUTING.md file as most of the time when he wants to set up a local development environment he doesn't do it necessarily to contribute to the project.

• @llucax showed the channels README as a potential improved way to structure the README.md

• At some point some different concepts were mixed up. The instructions in the CONTRIBUTING.md files are to set up a local development environment, not building from sources.

Some notes on why the current approach

• Currently the instructions are in the CONTRIBUTING.md file because GitHub gives it a special meaning and will automatically show a link to that file when people want to contribute back, for example sending a PR or opening a issue.

• When it comes to documentation, we want to have something that it is useful and usable both in GitHub and the generated docs (using mkdocs).

• The "Local development" section include other information, not only how to create this environment, like how to run tests, how to generate the documentation, etc. It is not clear to me if people not wanting to contribute to the project need this information too or not.

Improvement suggestions

• My personal opinion is that it would be nice to keep the instructions there, so people wanting to contribute to the project don't need to follow even more links.

• I see 4 things that could be explained in the README.md / user guide (docs/...) / CONTRIBUTING.md file related to this:

  • Installing from pip (should be in the README and user guide IMHO)
  • Installing from sources (trivial with pip, just pip install <source directory>, should probably be in the README and user guide, the contributing guide has that too but installing in editable mode for easier development testing).
  • Building from sources (hardly needed in python, but we could include it, no idea where or who would be the target of this information, it is just pip install build; python -m build).
  • Setting up a local development environment (I think it should be in the contributing guide, to be honest I don't see much point in having it anywhere else)

• We could make the current link to the contributing guide in the README more easy to read, so it is more obvious that those instructions are found there. Maybe add an explicit section "Setting up a local development environment" that points to that section of the CONTRIBUTING.md file.

• We could separate more clearly the CONTRIBUTING.md guide with sections for casual contributors (setting up a dev environment) and maintainers (release process).

[david-natingga-frequenz]

Building from sources is necessary in order to do a local install. Please, note that the following instructions are not trivial, especially for most of the developers who are not experts in Python:

git submodule init
git submodule update
git submodule update --remote

python -m pip install --upgrade pip
pip install build
python -m build
python -m pip install -e .[dev-noxfile]

Maybe a person wants to just modify the code for themselves locally to try something out (this was the case of Costas). There are also other reasons one has to setup the project locally. It does not mean they intend to contribute. So the instructions should clearly be visible as others pointed out.

[nhatcher-frequenz]

I like how this project does the split:
https://github.com/gitbutlerapp/gitbutler

[llucax]

After a short meeting we agreed on doing these improvements:

• Split CONTRIBUTING.md into DEVELOPMENT.md (local development setup) and docs/maintainers.md (for instructions for maintainers of the project, this could potentially go to an external docs/policies repo).
• CONTRIBUTING.md to have only information relevant to do contributions, like PRs or creating issues. Examples:
  • https://github.com/gitbutlerapp/gitbutler/blob/master/CONTRIBUTING.md
• Add cross-linking of docs where appropriate.

[llucax]

I create an issue with these conclusions and some more details on how to implement this:

• Improve and split CONTRIBUTING.md #266

If you have any comments, I recommend to make them here, at least if they are likely to trigger more discussion, so we can keep the issue as clean as possible.