Clean up documentation

docs/developer_documentation/workflows/changelog.md

@@ -1,6 +1,33 @@
 # Changelog fragments
 
-```{include} ../../../CONTRIBUTING.md
-:start-after: "## Changelog fragments"
-:end-before: "## Make a release"
+We try to add changelog fragments when we make changes so that we can show users what we've done. These fragments are small text files that contain a summary of changes. When we make a release, we compile these into a full changelog using [towncrier](https://pypi.org/project/towncrier/).
+
+Each changelog fragment should contain a short and meaningful summary of changes and include the issue number (where applicable). For example:
+
+```text
+Fixed broken audio player on Chrome 42 for ogg files (#567)
+```
+
+If there's no issue, insert the merge request identifier instead:
+
+```text
+Fixed a typo in landing page copy (!342)
+```
+
+## Naming
+
+Changelog fragments use the following naming convention: `changes/changelog.d/<name>.category>`. The `<name>` can be anything that describes your work, or the issue ID. The category can be one of the following:
+
+- `feature` – a new feature
+- `enhancement` – an extension of an existing feature
+- `bugfix` – a bugfix or patch
+- `refactoring` – refactored code
+- `doc` – new documentation
+- `i18n` – internationalization-related work
+- `misc` – any work that doesn't fit into the above categories
+
+You can create these files manually or use the following command to create a fragment:
+
+```sh
+towncrier new --edit $issue.$category
 ```

docs/developer_documentation/workflows/git.md

@@ -1,6 +1,53 @@
 # Git workflow
 
-```{include} ../../../CONTRIBUTING.md
-:start-after: "## Git workflow"
-:end-before: "## Changelog fragments"
+Funkwhale uses GitLab's merge requests to manage changes. The workflow looks like this:
+
+1. Assign the issue you are working on to yourself, or create one if it doesn't exist
+2. Create a fork of the project
+3. Check out the `develop` branch. If you're making a minor change (such as fixing a typo) you can check out the `stable` branch
+4. Create a new branch based on the checked out branch. Make sure to give your branch a meaningful name and include the issue number if required
+5. Work on your changes locally. Try to keep each commit small to make reviews easier
+6. Add a changelog fragment summarizing your changes
+7. Lint the codebase using the following command:
+
+    ::::{tab-set}
+
+    :::{tab-item} API code
+
+    ```sh
+    black --check --diff . # Run the black linter in the project root to highlight any new issues
+    ```
+
+    :::
+
+    :::{tab-item} Frontend code
+
+    ```sh
+    cd front
+    yarn run eslint # Run eslint in the front directory
+    ```
+
+    :::
+
+    ::::
+
+8. Push your branch
+9.  Create a merge request in the GitLab frontend
+10. We'll review your request and feed back
+
+```{mermaid}
+%%{init: { 'gitGraph': {'mainBranchName': 'stable'} } }%%
+    gitGraph
+        commit
+        branch develop
+        commit
+        commit
+        branch feature
+        commit
+        commit
+        checkout develop
+        merge feature
+        commit
+        checkout stable
+        merge develop
 ```

docs/developer_documentation/workflows/release.md

@@ -1,5 +1,107 @@
 # Make a release
 
-```{include} ../../../CONTRIBUTING.md
-:start-after: "## Make a release"
-```
+Once we're ready to release a new version of the software, we can use the following process:
+
+1. Export the new release version
+
+    ```sh
+    export NEXT_RELEASE=1.3.0
+    ```
+
+2. Export the previous release version
+
+    ```sh
+    export PREVIOUS_RELEASE=1.2.9
+    ```
+
+3. Pull the latest version of the `develop` branch. Use `stable` if you're releasing a bugfix.
+
+    ::::{tab-set}
+
+    :::{tab-item} Bugfix release
+    :sync: bugfix
+
+    ```sh
+    git checkout stable
+    git pull
+    ```
+
+    :::
+
+    :::{tab-item} Feature release
+    :sync: feature
+
+    ```sh
+    git checkout develop
+    git pull
+    ```
+
+    :::
+
+    ::::
+
+4. Compile the changelog
+
+    ```sh
+    towncrier build --version $NEXT_RELEASE
+    ```
+
+5. Check the output and fix typos and mistakes
+6. Add a list of contributors
+
+    ```sh
+    python3 scripts/get-contributions-stats.py $NEXT_RELEASE # Output a list of contributors
+    git log $PREVIOUS_RELEASE.. --format="- %aN" --reverse | sort | uniq # Get a list of all commit authors
+    nano CHANGELOG # Add these lists to the CHANGELOG
+    ```
+
+7. Update the `__version__` variable to the next release version
+
+    ```sh
+    nano api/funkwhale_api/__init__.py
+    ```
+
+8. Commit all changes
+
+    ```sh
+    git add .
+    git commit -m "Version bump and changelog for $NEXT_RELEASE"
+    ```
+
+9. Create a tag
+
+    ```sh
+    git tag $NEXT_RELEASE
+    ```
+
+10. Publish the new tag to GitLab
+
+    ```sh
+    git push --tags && git push
+    ```
+
+11. Merge your changes into the alternate branch
+
+    ::::{tab-set}
+
+    :::{tab-item} Bugfix release
+    :sync: bugfix
+
+    ```sh
+    git checkout develop && git merge stable && git push
+    ```
+
+    :::
+
+    :::{tab-item} Feature release
+    :sync: feature
+
+    ```sh
+    git checkout stable && git merge develop && git push
+    ```
+
+    :::
+
+    ::::
+
+Don't forget to create a blog post to announce the new release!