From 489f297fbd3523985861d42ea65bb9b0918f4471 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 29 Aug 2022 11:18:28 +0200 Subject: [PATCH] docs: Move build instructions and improve contributing guidelines Co-authored-by: Alexandre Franke Part-of: --- CONTRIBUTING.md | 163 +++++++++++++++++++++++++++++++++++++++++++++--- README.md | 70 +++------------------ 2 files changed, 162 insertions(+), 71 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 722e9d60..0868c108 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,165 @@ # Contributing -## Workflow +## Newcomers [Fractal](https://gitlab.gnome.org/GNOME/fractal/) follows the [GNOME Newcomers workflow](https://wiki.gnome.org/Newcomers/). Follow these pages to learn how to contribute. -We only support building with [flatpak](https://flatpak.org/) using [GNOME Builder](https://wiki.gnome.org/Apps/Builder). -If you insist on using any other method, they may work, but you will be on your own. +Here are also a few links to help you get started with Rust and the GTK Rust bindings: -You will need to manually install the latest version of the Rust extension of the FreeDesktop SDK. -To do this, just run `flatpak install --user org.freedesktop.Sdk.Extension.rust-stable//21.08` +- [Learn Rust](https://www.rust-lang.org/learn) +- [GUI development with Rust and GTK 4](https://gtk-rs.org/gtk4-rs/stable/latest/book) +- [gtk-rs website](https://gtk-rs.org/) -## Merge requests +[The Rust docs of our application](https://gnome.pages.gitlab.gnome.org/fractal/) might also be +useful. -We expect all code contributions to be correctly formatted. -Before submitting a merge request, please run `cargo fmt` on your branch to ensure this is the case. -It is also recommended to run `cargo clippy` as that will catch common errors and improve the quality of your submissions. +Don't hesitate to join [our Matrix room](https://matrix.to/#/#fractal:gnome.org) to come talk to us +and ask us any questions you might have. + +## Build Instructions + +### Prerequisites + +Fractal is written in Rust, so you will need to have at least Rust 1.60 and Cargo available on your +system. You will also need to install the Rust nightly toolchain to be able to run our +[pre-commit hook](#pre-commit). + +If you're building Fractal with Flatpak (via GNOME Builder or the command line), you will need to +manually add the necessary remotes and install the required FreeDesktop extensions: + +```sh +# Add Flathub-beta and the gnome-nightly repo +flatpak remote-add --user --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo +flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo + +# Install the gnome-nightly Sdk and Platform runtime +flatpak install --user gnome-nightly org.gnome.Sdk//master org.gnome.Platform//master + +# Install the required rust-stable extension from Flathub-beta +flatpak install --user flathub-beta org.freedesktop.Sdk.Extension.rust-stable//22.08beta + +# Install the required llvm extension from Flathub-beta +flatpak install --user flathub-beta org.freedesktop.Sdk.Extension.llvm14//22.08beta +``` + +### GNOME Builder + +Using [GNOME Builder](https://wiki.gnome.org/Apps/Builder) with [flatpak](https://flatpak.org/) is +the recommended way of building and installing Fractal. + +By default, GNOME Builder should select the `org.gnome.Fractal.Devel.json` manifest, which is the +manifest used for building the nightly version. It is recommended to switch to the +`org.gnome.Fractal.Hack.json` manifest which will build much faster. + +### Flatpak via fenv + +As an alternative, [fenv](https://gitlab.gnome.org/ZanderBrown/fenv) allows to setup a flatpak +environment from the command line and execute commands in that environment. + +First, install fenv: + +```sh +# Clone the project somewhere on your system +git clone https://gitlab.gnome.org/ZanderBrown/fenv.git + +# Move into the folder +cd fenv + +# Install fenv with Cargo +cargo install --path . +``` + +You can now discard the `fenv` directory if you want. + +After that, move into the directory where you cloned Fractal and setup the project: + +```sh +# Setup the flatpak environment +fenv gen build-aux/org.gnome.Fractal.Hack.json + +# Initialize the build system +fenv exec -- meson --prefix=/app _build +``` + +Finally, build and run the application: + +```sh +# Build the project +fenv exec -- ninja -C _build + +# Install the application in the flatpak environment +fenv exec -- ninja -C _build install + +# Launch Fractal +fenv exec ./_build/src/fractal +``` + +To test changes you make to the code, re-run these three last commands. + +### Install the flatpak + +Some features that interact with the system require the app to be installed to test them (i.e. +notifications, command line arguments, etc.). + +Move inside the `build-aux` folder and then build and install the app: + +```sh +cd build-aux +flatpak-builder --user --install app org.gnome.Fractal.Hack.json +``` + +It can then be entirely removed from your system with: + +```sh +flatpak remove --delete-data org.gnome.Fractal.Hack +``` + +### GNU/Linux + +If you decide to ignore our recommendation and build on your host system, outside of Flatpak, you +will need Meson and Ninja. + +```sh +meson . _build --prefix=/usr/local +ninja -C _build +sudo ninja -C _build install +``` + +## Pre-commit + +We expect all code contributions to be correctly formatted. To help with that, a pre-commit hook +should get installed as part of the building process. It runs the `scripts/checks.sh` script. It's a +quick script that makes sure that the code is correctly formatted with `rustfmt`, among other +things. Make sure that this script is effectively run before submitting your merge request, +otherwise CI will probably fail right away. + +You should also run `cargo clippy` as that will catch common errors and improve the quality of your +submissions and is once again checked by our CI. + +## Commit Please follow the [GNOME commit message guidelines](https://wiki.gnome.org/Git/CommitMessages). + +## Merge Request + +Before submitting a merge request, make sure that [your fork is available publicly](https://gitlab.gnome.org/help/user/public_access.md), +otherwise CI won't be able to run. + +Use the title of your commit as the title of your MR if there's only one. Otherwise it should +summarize all your commits. If your commits do several tasks that can be separated, open several +merge requests. + +In the details, write a more detailed description of what it does. If your changes include a change +in the UI or the UX, provide screenshots in both light and dark mode, and/or a screencast of the +new behavior. + +Don't forget to mention the issue that this merge request solves or is related to, if applicable. +GitLab recognizes the syntax `Closes #XXXX` or `Fixes #XXXX` that will close the corresponding +issue accordingly when your change is merged. + +We expect to always work with a clean commit history. When you apply fixes or suggestions, +[amend](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---amend) or +[fixup](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt) +and [squash](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash) your +previous commits that you can then [force push](https://git-scm.com/docs/git-push#Documentation/git-push.txt--f). diff --git a/README.md b/README.md index 89ef7918..79b861d2 100644 --- a/README.md +++ b/README.md @@ -57,66 +57,18 @@ flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.or flatpak install --user gnome-nightly org.gnome.Fractal.Devel ``` -## Build Instructions +### Runtime Dependencies -### Minimum Rust version +Fractal doesn't store your **password** but uses [Secret Service](https://www.freedesktop.org/wiki/Specifications/secret-storage-spec/) +to store your other **credentials** so you should have something providing that service on your +system. If you're using GNOME or KDE this should work for you out of the box with gnome-keyring or +ksecretservice. -To build Fractal, Rust 1.60 is required. For development, you'll need to install the nightly -toolchain to be able to run our pre-commit hook that validates the formatting and lints the Rust -code. +## Contributing -### Flatpak +### Code -Flatpak is the recommended way of building and installing Fractal. - -First you need to make sure you have the GNOME SDK and Rust toolchain installed. - -```sh -# Add Flathub-beta and the gnome-nightly repo -flatpak remote-add --user --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo -flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo - -# Install the gnome-nightly Sdk and Platform runtime -flatpak install --user gnome-nightly org.gnome.Sdk//master org.gnome.Platform//master - -# Install the required rust-stable extension from Flathub-beta -flatpak install --user flathub-beta org.freedesktop.Sdk.Extension.rust-stable//22.08beta - -# Install the required llvm extension from Flathub-beta -flatpak install --user flathub-beta org.freedesktop.Sdk.Extension.llvm14//22.08beta -``` - -
-

ℹ️ The instructions below will build the same binary as the one available on the GNOME nightly -repo. This is an optimised build so it can take a few minutes.

- -

If you're building Fractal for development, use the org.gnome.Fractal.Hack.json manifest -instead.

-
- -Move inside the `build-aux` folder and then build and install the app: - -```sh -cd build-aux -flatpak-builder --user --install app org.gnome.Fractal.Devel.json -``` - -Fractal Next can then be entirely removed from your system with: - -```sh -flatpak remove --delete-data org.gnome.Fractal.Devel -``` - -### GNU/Linux - -If you decide to ignore our recommendation and build on your host system, -outside of Flatpak, you will need Meson and Ninja (as well as Rust and Cargo). - -```sh -meson . _build --prefix=/usr/local -ninja -C _build -sudo ninja -C _build install -``` +Please follow our [contributing guidelines](CONTRIBUTING.md). ### Translations @@ -124,12 +76,6 @@ Fractal is translated by the GNOME translation team on [Damned lies](https://l10 Find your language in the list on [the Fractal module page on Damned lies](https://l10n.gnome.org/module/fractal/). -### Password Storage - -Fractal uses [Secret Service](https://www.freedesktop.org/wiki/Specifications/secret-storage-spec/) -to store the password so you should have something providing that service on your system. If you're -using GNOME or KDE this should work for you out of the box with gnome-keyring or ksecretservice. - ## Frequently Asked Questions * Does Fractal have encryption support? Will it ever?