From 1f011bd9189c994e12e0d6d728025b9dd8147223 Mon Sep 17 00:00:00 2001
From: Clement Tsang <34804052+ClementTsang@users.noreply.github.com>
Date: Wed, 14 Aug 2024 02:44:32 +0000
Subject: [PATCH] docs: update doc about mkdocs, changelog, and versioning
 (#1561)

* docs: update doc about mkdocs

* docs: more readme docs wording

* add some details about versioning
---
 CHANGELOG.md   | 23 +++++++++++++++++++----
 docs/README.md | 10 ++++++----
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6860b4871..9cc74a936 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,9 +1,24 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project will be documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versioning for this project is based on [Semantic Versioning](https://semver.org/spec/v2.0.0.html). More specifically:
+
+**Pre 1.0.0 (current)**:
+
+- Patch versions should aim to only contain bug fixes or non-breaking features/changes.
+- Minor versions may break things.
+
+**Post 1.0.0**:
+
+- Patch versions should only contain bug fixes.
+- Minor versions should only contain forward-compatible features/changes.
+- Major versions may break things.
+
+That said, these are more guidelines rather than hardset rules, though the project will generally try to follow them.
+
+---
 
 ## [0.11.0]/[0.10.3] - Unreleased
 
@@ -43,7 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changes
 
-- [#1276](https://github.com/ClementTsang/bottom/pull/1276): GPU functionality is now tied behind the `--enable_gpu` flag. This will likely be changed in the future.
+- [#1276](https://github.com/ClementTsang/bottom/pull/1276): NVIDIA GPU functionality is now tied behind the `--enable_gpu` flag. This will likely be changed in the future.
 - [#1344](https://github.com/ClementTsang/bottom/pull/1344): Change the `group` command line-argument to `group_processes` for consistency with the config file option.
 - [#1376](https://github.com/ClementTsang/bottom/pull/1376): Group together related command-line arguments in `-h` and `--help`.
 - [#1411](https://github.com/ClementTsang/bottom/pull/1411): Add `time` as a default column.
diff --git a/docs/README.md b/docs/README.md
index 66092dd07..591c799a6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,7 +7,8 @@ Documentation is currently built using Python 3.11, though it should work fine w
 
 ## Running locally
 
-One way is to just run `serve.sh`. Alternatively, the manual steps are:
+One way is to just run `serve.sh`. Alternatively, the manual steps are, assuming your current working directory
+is the bottom repo:
 
 ```bash
 # Change directories to the documentation.
@@ -26,16 +27,17 @@ venv/bin/mkdocs serve
 
 ## Deploying
 
-Deploying is done via [mike](https://github.com/jimporter/mike).
+Deploying is done via [mike](https://github.com/jimporter/mike) in order to get versioning. Typically,
+this is done through CI, but can be done manually if needed.
 
-### Nightly
+### Nightly docs
 
 ```bash
 cd docs
 mike deploy nightly --push
 ```
 
-### Stable
+### Stable docs
 
 ```bash
 cd docs