[docs] update: building + plans + management

docs/design/main.md

@@ -1,6 +1,6 @@
 # Internal design
 
-*might be outdated!*
+*might be outdated!* TODO
 
 * [Data](data.md)
 * [Actions](actions.md)

docs/development.md

@@ -2,11 +2,28 @@
 
 ## Current state
 
-* [internal design](design/main.md)
+* [internal design](design/main.md) (TODO)
+* plugins (TODO)
 
 ## Forward
 
 * [broad, long-term plans and ideas](plans/goals.md)
 * [short-term detail](plans/todo.md)
 * [feedback](feedback)
-* [bugs](bugs.md)
+* [bugs](bugs.md)
+
+## Management
+
+We're on a rolling release model.
+
+There are two permanent branches in the git repository:
+* `devel` - the __current development state__. New features will be added here quickly. _Might be unstable!_
+* `master` - the __released/stable state__. Follows the `devel` branch with a time delay for testing.
+
+Larger features will be merged from feature branches into `devel`, small ones might be committed directly.
+
+Our test team (i.e. me) will use the program in the field. We also have a [CI](../.github/workflows/cmake-multi-platform.yml) with some automatic tests. When found stable enough, `devel` will be merged into `master` irregularly.
+
+Every 2-4 months there will be a larger [release on github](https://github.com/momentarylapse/tsunami/releases) with binaries. 
+
+We've switched to a date based versioning scheme (e.g. `v2024-10`), since semantic version numbers (`1.2.3`) are scary. Versions are automatically taken from git. Tags define releases and non-release builds automatically identify the current git commit hash.

docs/how-to-build.md

@@ -9,27 +9,27 @@ Install libraries (the developer version):
 
 ### Arch / Manjaro
 
-```
+```bash
 sudo pacman -S gtk4 libogg libvorbis flac fftw libpulse alsa-lib libunwind
 ```
 
 ### Fedora
 
-```
+```bash
 sudo dnf install libogg-devel libvorbis-devel flac-devel fftw3-devel pulseaudio-libs-devel alsa-lib-devel libunwind-devel
 ```
 
 ### Debian / Ubuntu
 
-```
+```bash
 sudo apt-get install git make g++
 sudo apt-get install libgtk-4-dev libogg-dev libvorbis-dev libflac-dev libfftw3-dev libpulse-dev libasound-dev libgl-dev libunwind-dev libportaudio19-dev
 ```
 
 ## Building, installing
 
 Assuming you are in the repository's root folder, type
-```
+```bash
 mkdir build
 cd build
 ccmake .. -GNinja
@@ -41,21 +41,13 @@ sudo ninja install   # optional
 By default, this will use **gtk4**. If you want to try **gtk3**, you can (in the `cmake ..` step) edit the option `GTK4_OR_GTK3` to "gtk3".
 
 
-<!---Alternatively, you can use **meson** to compile (might be broken...):
-```
-meson build
-cd build
-ninja
-```
---->
-
 
 ## Running
 
-If you installed via `sudo make install`, tsunami should be registered in your desktop environment. Probably just find the friendly icon in the menu and click. You can also open a terminal and type `tsunami`.
+If you installed via `sudo ninja install`, tsunami should be registered in your desktop environment. Probably just find the friendly icon in the menu and click. You can also open a terminal and type `tsunami`.
 
 Tsunami can also be used without installing. Open a terminal, and
-```
+```bash
 cd <REPOSITORY-ROOT>  # important to run the program from here!
 ./build/tsunami
 ```
@@ -73,7 +65,9 @@ Follow the steps here: https://github.com/wingtk/gvsbuild
 
 But instead of `gvsbuild build gtk4` run
 
-```gvsbuild build gtk4 libadwaita adwaita-icon-theme```
+```bash
+gvsbuild build gtk4 libadwaita adwaita-icon-theme
+```
 
 ## Visual Studio
 
@@ -91,15 +85,15 @@ Also **experimental** support, using `homebrew`, `gtk4` and `coreaudio` or `port
 
 ## Preparation: installing libraries
 
-```
+```bash
 brew install cmake extra-cmake-modules pkg-config ninja
 brew install fftw libogg libvorbis flac
 brew install gtk4 libadwaita portaudio
 ```
 
 ## Building
 
-```
+```bash
 # (in the repository root folder)
 mkdir build
 cd build
@@ -113,8 +107,17 @@ Installing is not supported!
 
 ## Running
 
-````
+````bash
 # (in the repository root folder)
 ./build/tsunami
 ````
 
+## App bundle
+
+You can build an .app bundle by following the [building](#building) steps, and adding
+```bash
+ninja bundle
+```
+
+The produced `tsunami.app` can be installed in the system, by dragging it into the `Applications` folder in `Finder`.
+

docs/plans/goals.md

@@ -1,20 +1,26 @@
 # Development plans (long-term)
 
-## gtk4 migration
-
-Mostly done, now.
-
 
 ## Windows version
 
-Multiple problems:
+Mostly working.
 
-* building with gtk on windows constantly breaks
-  * `vcpkg` worked for a short time, before breaking automatic include directories
-  * ok, a mix of `vcpkg` and `gvsbuild` seems to work
+Remaining issues:
+
+* `gtk` is annoying on windows
 * not all utf-8 supported?!?
-* my `kaba` JIT compiler has not been tested on windows for a while, might need fixes
+* installing and file associations would be nice
+
+
+## MacOS version
+
+Also mostly working on MacBooks with (aarch64) M1 chip or newer.
+
+Remaining issues:
 
+* (properly) distributable app bundles
+* file associations
+* `CoreAudio`
 
 ## Modular synthesizers