Update docs and website

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for your interest in helping Cartero grow! This document will
+provide information and tips on how to help the project.
+
+## Contributing with code
+
+This project is highly appreciative of contributions. If you know about Rust,
+GTK or the GNOME technologies and want to help during the development, you can
+contribute if you wish. [Fork the project][fork] and commit your code.
+
+Some checklist rules before submitting a pull request:
+
+- **Use a feature branch**, do not make your changes in the trunk branch
+  directly.
+
+- **Rebase your code** and make sure that you are working on top of the most
+  recent version of the trunk branch, in case something has changed while you
+  were working on your code.
+
+- **Update the locales** if you changed strings. The ninja target that you are
+  looking for is called `cartero-update-po` (such as `ninja -C build
+cartero-update-po`). Don't worry, you don't have to translate the strings by
+  yourself, but make sure that the new templates are added to the .po and .pot
+  files.
+
+- **Use the pre-commit hook**. The pre-commit hook will validate that your code
+  is formatted. It should be automatically configured if you run Meson in
+  development mode (`-Dprofile=development`), but you can install it on your
+  own or run `hooks/pre-commit.hook`.
+
+The project is starting small, so if you want to do something big, it is best
+to first start a discussion thread with your proposal in order to see how to
+make it fit inside the application.
+
+This project is published with the GNU General Public License 3.0 or later.
+Therefore, your contribution will be checked out into the repository under that
+license. **Make sure you are comfortable with the license before contributing**.
+Specifically, while you retain copyrights of your contribution, you acknowledge
+that you allow anyone to use, study or distribute any code you write under the
+terms of that license.
+
+This application is not affiliated with the GNOME project, but we follow the
+[GNOME Code of Conduct][coc] anyway as a guideline and we expect you to follow
+it when interacting with the repository.
+
+## Contributing with translations
+
+Do you want to use Cartero in your language? We are using [Weblate][weblate]
+to coordinate and translate comfortably this project using a web interface.
+Make an account and start proposing strings and they will be added to the
+application. That will also entitle you as a contributor!
+
+## Contributing with feedback
+
+Cartero is still getting new features, and hopes to be as useful as it can be.
+Found a bug or something is wrong? Report it. An use case you are missing?
+Report it. Show us how you integrate Cartero on your workflow so that we can
+build our diverse list of use cases.
+
+[fork]: https://github.com/danirod/cartero/fork
+[weblate]: https://hosted.weblate.org/projects/cartero/
+[coc]: https://conduct.gnome.org

HACKING.md

@@ -2,101 +2,83 @@
 
 Some additional instructions for people interested in running cartero.
 
-## "Meson sucks, stick with Cargo"
+## TL;DR
 
-I don't disagree with this statement, in fact. I fail to see exactly how is
-Meson better than CMake when it does the same tasks, but sometimes worse, since
-Meson is not as flexible and extensible as CMake is, and this is seen as how
-fragile is the integration between Meson and Rust.
+This project makes use of Meson, whether you like it or not. If you are used
+to GNOME app development, you might already like it. Otherwise, you'll have to
+accept it.
 
-Meson is as opinionated on how to build a program as Cargo is. Meson will call
-Cargo when it is time to build the executable file by just issuing the `cargo
-build` external command, but the build script still has to copy a lot of files
-so that both tools can coexist without shilling at each other publicly on your
-terminal.
+However, treating this source code workspace as a standard Rust project makes
+sense because then you can use autocompletion and other Rust tools. Therefore,
+to make things easier, there is an aux script that you can use to quickly rebuild
+the application data files (resource bundles, translations, icons, GLib schemas)
+and move them to the `target/` directory:
 
-This project is making use of it because of two reasons:
-
-* Because there is actually more than Rust for this project and Meson knows
-  how to compile the resource bundles, update the locales and generate the
-  desktop files for Cartero.
-
-* Because it ticks a checkbox.
-
-To be honest, if you are not a try-hard GNOME developer, you will find casually
-hacking applications based on the GNOME stack difficult and cumbersome because
-some of the following reasons mean that "installing" the app, or at least the
-data files (/usr/share), is necessary to run the program.
-
-* Many applications will make use of the GSettings framework to load and store
-  application settings, and GSettings require the GSchemas to be installed
-  globally in order to use them.
-
-* Some features, such as application notifications, may not work at all unless
-  the application is installed and thus recognised by the GNOME notifications
-  framework.
-
-* Some applications insist on using absolute and hardcoded locations when
-  loading translation files and GResource bundles, such as always trying to load
-  from $prefix/share. Therefore, unless the application is installed, the file
-  system hierarchy will not be fully set.
-
-A valid answer to these complains would be "just compile and debug a Flatpak",
-but this will not be the taste of some people and I understand that.
-
-My suggestion however is to just use a local installdir such as $PWD/install,
-and just run `ninja install` into your prefix as part of the compilation
-process. This doesn't require root privileges (DO NOT SUDO WHILE TESTING OR
-RUNNING CARTERO FOR GOD'S SAKE) and it can be easily cleaned with `rm -rf
-install` later.
+```
+build-aux/cargo-build.sh
+```
 
-### Alternative build script
+You should check the contents of the script before running it. But it will
+precompile parts of the application using meson and the run `cargo build`. You
+can then call `cargo r`, `cargo t` or whatever you plan on doing with the code.
 
-Precisely, that's what my alternative build scripts do.
+## "But Meson sucks, stick with Cargo!"
 
-**build-aux/meson-build.sh** is a script that doesn't do anything different than
-what the README.md file indicates, but it automates it in order to do it very
-quick. So running **build-aux/meson-build.sh** will run `meson setup` and `ninja
-&& ninja install` for you, using the following paths:
+I don't disagree with this statement, in fact. I feel like Meson is not as
+flexible as other build systems like CMake, specially when it comes to creating
+and running custom commands. This has the effect of making the integration
+between Rust and Meson very fragile.
 
-* It will build the application into $PWD/build.
-* It will install the application to $PWD/install.
+Meson is an opinionated tool. However, Cargo is also a very opinionated tool.
+Meson will invoke Cargo when it is time to build the executable file by just
+issuing the `cargo build` external command, but the build script still has to
+copy a lot of files to Meson's build directory so that both tools can coexist
+without shilling at each other publicly on your terminal.
 
-So a quick workflow for hacking Cartero while using the script would be:
+Why does Cartero use Meson?
 
-```sh
-build-aux/meson-build.sh && install/bin/cartero
-```
+* Because there is actually more than Rust for this project and Meson knows
+  how to compile the resource bundles, update the locales and generate the
+  desktop files for Cartero.
 
-As you probably have noticed, Meson sucks, and sometimes it will not detect that
-the GResource file has to be recompiled, despite my attempts to make sure that
-every target in my meson.build files has dependencies properly set.
+* Because it ticks a checkbox when it comes to aligning to the GNOME guidelines,
+  which this project intends to follow, even though Cartero supports a wide
+  variety of operating systems and desktop environments.
 
-If you notice while running meson-build.sh that the application crashes or does
-not detect the changes that you made to the user interface files, my suggestion
-is to just run `rm -rf build/data` and recompile. Meson should see that the
-resource file is missing and it should create it from scratch.
+Due to these things, switching to `build.rs` will not fix things at all, it
+will just turn the tables upside down, making Rust code easier to build at the
+expense of making every non-Rust resource way more difficult to compile.
 
-### But I want to use cargo build
+## But I want to use cargo build
 
 I know, and it makes a lot of sense, because chances are that you are using a
-text editor or IDE (this includes GNOME Builder) with some dveloper tools such
+text editor or IDE (this includes GNOME Builder) with some developer tools such
 as rust-analyzer, and this directory will probably want to use `target` to do
 its stuff and provide completions.
 
-As long as you have the dependencies in your system (GTK, SourceView5...), you
-should be able to just `cargo build` the application and **it has to compile**.
-If `cargo build` does not work, that's a bug.
+`cargo build` will just care about compiling the application provided that you
+have every system dependency installed (GTK, GtkSourceView...). It doesn't care
+about whether the resources or translations have been bundled.
+
+Theferore, `cargo build` has to work anyway. You should be able to just run
+`cargo build` in a clean workspace and it has to compile the application.
+**If it doesn't work, then that's a bug.**
 
 However, since you need the resource bundle and the translation files, `cargo
 run` will not work unless you place them in your target directory as well, as I
 tried to explain above.
 
-The good thing is that Cargo actually builds your application into a
-subdirectory of `target`, such as `target/debug` or `target/release`. In this
-case, the `debug` and `release` directories act as the bindir for cartero, so
-all you have to do is to create a `target/share` directory, place all the
-datafiles in `target/share`, and that's it.
+Cartero will follow the standard UNIX directory standards. Therefore, it expects
+to be running inside some kind of `bindir` and by default it will assume that the
+datafiles are in `../share`.
+
+In normal circunstances, your bindir will be `/usr/bin` and therefore the datafiles
+will be in `/usr/bin/../share => /usr/share`.
+
+However, because Cargo will build the application into a subdirectory inside of
+`target`, whether that's `target/debug` or `target/release`, this directory can
+act as a valid `bindir`. If the datafiles are placed into `target/share`, then
+Cartero has to run.
 
 **And that is exactly what build-aux/cargo-build.sh** does. So if you want to
 use `cargo build` and `cargo run`, just use `build-aux/cargo-build.sh`, which
@@ -109,25 +91,6 @@ to craft a valid pkgdatadir. It will then proceed to deploy them into
 build-aux/cargo-build.sh && cargo run
 ```
 
-Just the same as above, if you notice that your user interface files are not
-updating, just run `rm -rf build/data` and try to compile the application again.
-
-### Two CARGO_HOMEs?
-
-One thing to point out is that Meson uses its own vendored CARGO_HOME directory
-and it compiles into a different target directory inside build. Therefore, if
-you mix both pipelines, you will probably see more often Cargo downloading and
-compiling dependencies.
-
-I think that the vendoring process made by Meson is correct and useful and thus
-I do not see this as a drawback. I'm just pointing this out because waiting for
-Cargo to compile dependencies suck and mixing `cargo build` with `meson` will
-make you wait more often.
-
-### Absolute directories
-
-Just as a note: Cartero does not make use of absolute paths. You should be able
-to run the application from any location, as long as there is a separate bindir
-and datadir. I placed this requirement for the future, since I want a Microsoft
-Windows installer to exist and I cannot just run cargo build inside the
-installer. (Or can I?!)
+If you notice that your user interface files are not updating or your translations
+are not being picked up, you can just run `rm -rf build/data` or `rm -rf target/share`
+and try again. (If you have to do this a lot, this is probably a bug.)