From 5973e6db72b640a7c951eab1ca17d3c9c87aee4b Mon Sep 17 00:00:00 2001 From: Clement Tsang <34804052+ClementTsang@users.noreply.github.com> Date: Mon, 12 Sep 2022 04:14:19 -0400 Subject: [PATCH] docs: adjust dev doc file structure, add build and deploy docs (#804) * docs: add separate section on development * docs: update instructions on writing docs * docs: add build and deploy docs --- .gitignore | 1 - docs/.gitignore | 2 + docs/content/contribution/development.md | 11 ---- .../contribution/development/build_process.md | 63 +++++++++++++++++++ .../development/deploy_process.md | 53 ++++++++++++++++ .../contribution/development/dev_env.md | 9 +++ .../contribution/development/logging.md | 9 +++ .../contribution/development/testing.md | 9 +++ docs/content/contribution/documentation.md | 29 +++++++-- .../contribution/issues-and-pull-requests.md | 2 - docs/mkdocs.yml | 8 ++- docs/requirements.txt | 2 +- 12 files changed, 177 insertions(+), 21 deletions(-) create mode 100644 docs/.gitignore delete mode 100644 docs/content/contribution/development.md create mode 100644 docs/content/contribution/development/build_process.md create mode 100644 docs/content/contribution/development/deploy_process.md create mode 100644 docs/content/contribution/development/dev_env.md create mode 100644 docs/content/contribution/development/logging.md create mode 100644 docs/content/contribution/development/testing.md diff --git a/.gitignore b/.gitignore index 431f9c97..82cce855 100644 --- a/.gitignore +++ b/.gitignore @@ -34,4 +34,3 @@ deny.toml # mkdocs site/ -docs/site diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..9b72d312 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +site/ +venv/ \ No newline at end of file diff --git a/docs/content/contribution/development.md b/docs/content/contribution/development.md deleted file mode 100644 index f388506b..00000000 --- a/docs/content/contribution/development.md +++ /dev/null @@ -1,11 +0,0 @@ -# Development - -!!! Warning - - This section is currently WIP. - -## Dev Environment - -## Logging - -## Testing diff --git a/docs/content/contribution/development/build_process.md b/docs/content/contribution/development/build_process.md new file mode 100644 index 00000000..09efe5cd --- /dev/null +++ b/docs/content/contribution/development/build_process.md @@ -0,0 +1,63 @@ +# Build Process + +!!! Warning + + This section is currently somewhat WIP. + +!!! Warning + + This section is intended for people who wish to work on/build/distribute bottom, not general users. + +## Overview + +bottom manages its own binary builds for nightly and stable release purposes. The core build workflow is handled by [`build_releases.yml`](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/build_releases.yml), called by a wrapper workflow for [nightly](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/nightly.yml) and [stable](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/deployment.yml) releases. Builds take place via GitHub Actions. + +The main things built are: + +- Binaries for various platforms +- MSI installer for Windows +- `.deb` package for Debian and its derivatives + +This documentation gives a high-level overview of the build process for each part. For the most up-to-date and detailed reference, definitely refer back to the [`build_releases.yml`](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/build_releases.yml) file. + +## Binaries + +Binaries are built currently for various targets. Note that not all of these are officially supported. The following general steps are performed: + +- Set up the Rust toolchain for the action runner. +- Enable cache. +- Build a release build with: + + - `--features deploy`, which disables unneeded dev features in bottom. + - `--locked` to lock the dependency versions. + - The following env variables set: + + - `BTM_GENERATE: true` + - `COMPLETION_DIR: "target/tmp/bottom/completion/"` + - `MANPAGE_DIR: "target/tmp/bottom/manpage/"` + + These generate the manpages and shell completions (see [Packaging](packaging-and-distribution.md) for some more information). + +- Bundle the binaries and manpage/completions. +- Cleanup. + +Some builds use [`cross`](https://github.com/cross-rs/cross) to do cross-compilation builds for architectures otherwise not natively supported by the runner. + +## MSI + +This builds a full Windows installer using [`cargo-wix`](https://github.com/volks73/cargo-wix). This requires some setup beforehand with some dependencies: + +- Net-Framework-Core (handled by Powershell) +- wixtoolset (handled by chocolatey) +- Rust toolchain + +After that, cache is enabled, and `cargo wix` takes care of the rest. + +## `.deb` + +Currently, `.deb` files are built for x86 and ARM architectures (`armv7`, `aarch64`). This is handled by [`cargo-deb`](https://crates.io/crates/cargo-deb). + +- For x86, this is handled natively with just `cargo-deb`. +- For ARM, this uses a Docker container, [cargo-deb-arm](https://github.com/ClementTsang/cargo-deb-arm), which correctly sets the dependencies and architecture for the generated `.deb` file. + +There are additional checks via `dpkg` to ensure the architecture is correctly set. diff --git a/docs/content/contribution/development/deploy_process.md b/docs/content/contribution/development/deploy_process.md new file mode 100644 index 00000000..b9664f79 --- /dev/null +++ b/docs/content/contribution/development/deploy_process.md @@ -0,0 +1,53 @@ +# Deploy Process + +!!! Warning + + This section is currently WIP. + +!!! Warning + + This section is intended for people who wish to work on/build/distribute bottom, not general users. + +## Overview + +bottom currently has two main deploy processes to worry about: + +- [Nightly](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/nightly.yml): a daily (00:00 UTC) GitHub action to build binary/installer files, and upload them to the [nightly release](https://github.com/ClementTsang/bottom/releases/tag/nightly). It can also be triggered manually as either a proper nightly release or a mock release. +- [Stable](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/deployment.yml): a stable deployment, triggered manually or upon creation of a valid tag. This is a GitHub action that builds binary/installer files and uploads them to a new GitHub release. + + Furthermore, this workflow does not handle the following deployments, which must be manually handled: + + - [Chocolatey](https://community.chocolatey.org/packages/bottom) + - [crates.io](https://crates.io/crates/bottom) + +## Nightly + +This is, for the most part, automatic, though it can also be used as a way of testing build workflow changes and seeing if binaries can be successfully built at all against all the targets we want to build for. + +If one does not want to actually update the nightly release, and just want to test the general builds and workflow, one can run the workflow manually on a branch of choice with "mock" set as the parameter. Changing it to anything else will trigger a non-mock run. + +## Stable + +This can be manually triggered, though the general use-case is setting a tag of the form `x.y.z` (after checking everything is good, of course). For example: + +```bash +git tag 0.6.9 && git push origin 0.6.9 +``` + +This will automatically trigger the deployment workflow, and create a draft release with the files uploaded. One still needs to fill in the details and release it. + +Furthermore, there are some deployments that are handled by maintainers of bottom that this workflow does not automatically finish. These must be manually handled. + +### Chocolatey + +Upon releasing on GitHub, [choco-bottom](https://github.com/ClementTsang/choco-bottom) will automatically be updated with a new PR with the correct deployment files for Chocolatey. Check the PR, merge it if it is correct, then pull locally and deploy following the instructions in the [README](https://github.com/ClementTsang/choco-bottom/blob/master/README.md). Make sure to test installation and running at least once before deploying! + +If done correctly, there should be a new build on Chocolatey, which will take some time to validate. + +### crates.io + +Validate everything builds properly and works (you should have done this before releasing though). If good, then deploying on crates.io is as simple as: + +```bash +cargo publish +``` diff --git a/docs/content/contribution/development/dev_env.md b/docs/content/contribution/development/dev_env.md new file mode 100644 index 00000000..2ad1cce6 --- /dev/null +++ b/docs/content/contribution/development/dev_env.md @@ -0,0 +1,9 @@ +# Development Environment + +!!! Warning + + This section is currently WIP. + +!!! Warning + + This section is intended for people who wish to work on/build/distribute bottom, not general users. diff --git a/docs/content/contribution/development/logging.md b/docs/content/contribution/development/logging.md new file mode 100644 index 00000000..5e35bcdd --- /dev/null +++ b/docs/content/contribution/development/logging.md @@ -0,0 +1,9 @@ +# Logging + +!!! Warning + + This section is currently WIP. + +!!! Warning + + This section is intended for people who wish to work on/build/distribute bottom, not general users. diff --git a/docs/content/contribution/development/testing.md b/docs/content/contribution/development/testing.md new file mode 100644 index 00000000..b6582e78 --- /dev/null +++ b/docs/content/contribution/development/testing.md @@ -0,0 +1,9 @@ +# Testing + +!!! Warning + + This section is currently WIP. + +!!! Warning + + This section is intended for people who wish to work on/build/distribute bottom, not general users. diff --git a/docs/content/contribution/documentation.md b/docs/content/contribution/documentation.md index b06d48ab..b39ca709 100644 --- a/docs/content/contribution/documentation.md +++ b/docs/content/contribution/documentation.md @@ -20,12 +20,33 @@ There are a few areas where documentation changes are often needed: 2. Where you're adding documentation will probably affect what you need to do: - - For changes to [`README.md`](https://github.com/ClementTsang/bottom/blob/master/README.md) and [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md), just follow the formatting provided and use any editor. + ### `README.md` or `CHANGELOG.md` - - For changes to the help menu, try to refer to the existing code within `src/constants.rs` on how the help menu is generated. + For changes to [`README.md`](https://github.com/ClementTsang/bottom/blob/master/README.md) and [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md), just follow the formatting provided and use any editor. - - For changes to the extended documentation, you'll want [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), and `mdx_truly_sane_lists` installed to provide live reloading and preview for your changes. You can do so through `pip` or your system's package managers. While you don't _need_ these, it'll probably help in making and validating changes. + ### Help menu - You may also want [Mike](https://github.com/jimporter/mike), but it isn't really needed. + For changes to the help menu, try to refer to the existing code within `src/constants.rs` on how the help menu is generated. + + ### Extended documentation + + For changes to the extended documentation, you'll probably want [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), `mdx_truly_sane_lists`, and optionally [Mike](https://github.com/jimporter/mike) installed to provide live reloading and preview for your changes. They aren't needed but it'll help with validating your changes. + + You can do so through `pip` or your system's package managers. If you use `pip`, you probably would want to do something like so through a venv: + + ```bash + # Starting from the repo root: + cd docs/ + + # Create venv and activate + python -m venv venv + source venv/bin/activate + + # Install requirements + pip install -r requirements.txt + + # Run mkdocs + venv/bin/mkdocs serve + ``` 3. Once you have your documentation changes done, submit it as a pull request. For more information regarding that, refer to [Issues, Pull Requests, and Discussions](../issues-and-pull-requests/). diff --git a/docs/content/contribution/issues-and-pull-requests.md b/docs/content/contribution/issues-and-pull-requests.md index 7207ad7e..e31d423a 100644 --- a/docs/content/contribution/issues-and-pull-requests.md +++ b/docs/content/contribution/issues-and-pull-requests.md @@ -1,7 +1,5 @@ # Issues, Pull Requests, and Discussions -Contribution in any way is appreciated, whether it is reporting problems, fixing bugs, implementing features, improving the documentation, etc. - ## Discussions Discussions are open [in the repo](https://github.com/ClementTsang/bottom/discussions). As for the difference between discussions and issues: diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 87a136e0..23c63890 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -5,7 +5,6 @@ site_url: https://clementtsang.github.io/bottom site_description: >- A customizable cross-platform graphical process/system monitor for the terminal. Supports Linux, macOS, and Windows. docs_dir: "content/" - # Project information repo_name: ClementTsang/bottom repo_url: https://github.com/ClementTsang/bottom @@ -149,6 +148,11 @@ nav: - "Contribution": - "Issues, Pull Requests, and Discussions": contribution/issues-and-pull-requests.md - "Documentation": contribution/documentation.md - - "Development": contribution/development.md - "Packaging and Distribution": contribution/packaging-and-distribution.md + - "Development": + - "Development Environment": contribution/development/dev_env.md + - "Testing": contribution/development/testing.md + - "Logging": contribution/development/logging.md + - "Build Process": contribution/development/build_process.md + - "Deploy Process": contribution/development/deploy_process.md - "Troubleshooting": troubleshooting.md diff --git a/docs/requirements.txt b/docs/requirements.txt index 4bee404c..d608a3f7 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ mkdocs == 1.3.1 mkdocs-material == 8.4.0 mkdocs-material-extensions == 1.0.3 -mdx_truly_sane_lists == 1.2 +mdx_truly_sane_lists == 1.3 mike == 1.1.2