diff options
78 files changed, 1342 insertions, 781 deletions
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d26baed5..b5548664 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -6,60 +6,40 @@ labels: "bug" assignees: "" --- -## Describe the bug - -_A clear and concise description of what the bug is and what the expected behaviour was. If applicable, add screenshots to help explain your problem:_ - -## How to reproduce - -_Steps on how to reproduce the behaviour. Please try to include this section so I can reproduce your problem in order to fix it. If you are using any runtime flags (i.e. `btm --group`) please mention them as part of this.:_ - -## bottom version - -_Use `btm -V` and report the version of bottom you have installed. Also, if you're not on the latest version, please [try that](https://github.com/ClementTsang/bottom/releases/latest) and see if the problem is already resolved._ +Before you report, please take a look at [Troubleshooting](https://clementtsang.github.io/bottom/troubleshooting) to see if there's already an answer to your problem. -## bottom config file (if used) +Also, **please fill in all fields if possible** - if the issue is too hard to reproduce or vague, it may not be fixed! -_If you're using a config file, please include it in the report._ - -## Installation method - -_How did you install bottom? Note if it's not a supported method, I may not be able to help you._ - -## Platform and environment information - -### Operating system, OS version, and architecture - -_Please specify your operating system, the version, and architecture, so I can try to replicate your environment as best as possible. Note that the officially supported platforms are:_ +## Describe the bug -- _macOS (`x86_64`)_ -- _Linux (`x86_64`, `i686`, `aarch64`)_ -- _Windows (`x86_64`, `i686`)_ +Give a high level description of the bug. -_If your platform is not listed, please be aware I do not officially support it and may be unable to fix this issue._ +## What operating system/architecture are you using? -### Terminal (i.e. urxvt, kitty, etc.) +Please mention what operating system, version, and architecture you're experiencing the problem on (ex: macOS 10.13, x86_64). Please also ensure that your system is [on the list of supported systems](https://github.com/ClementTsang/bottom#support) - bug reports on unsupported systems are likely to be closed. -_Sometimes this matters, so please mention your terminal/terminal emulator._ +## What terminal are you using `bottom` on? -### Shell (i.e. zsh, bash, etc.) +Please mention what terminal/terminal emulator you are using `bottom` on (ex: Konsole, Kitty). -_Again, sometimes this matters, so please mention your shell type if possible._ +## What version are you on? -### Miscellaneous system info +Please ensure that the bug still exists on the [latest stable release](https://github.com/ClementTsang/bottom/releases/latest) or newer (i.e. nightly). If so, mention +what version you are using here. -_Not totally necessary, but if possible, include details like:_ +## How did you install `bottom`? -_RAM size:_ +Please mention how you installed `bottom`. If you manually compiled it, please also mention your _Rust version_. -_SWAP size:_ +## How can we reproduce this? -_CPU and number of cores:_ +Provide detailed steps on _how_ to reproduce your problem, to the best of your ability. Be as detailed as possible, and include config files or flags if relevant. +If maintainers cannot reproduce the bug, it will be very hard to fix it. -### Rust version +## What is the actual behaviour? -_Check this with `rustc --version`. This is only relevant if your version of bottom isn't from a pre-built binary (i.e. Cargo). Otherwise, feel free to skip._ +What is the _actual_ result of the given steps? Be detailed. Please include screenshots if the issue is a visual one. -## Additional context +## What is the expected behaviour? -_If anything hasn't been covered by the above categories, feel free to include it here:_ +What do you believe the expected behaviour should be given these steps? diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 49594883..827e2006 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature request -about: Got a good idea that hasn't already been mentioned? Suggest it! +about: Got a good idea that hasn't already been suggested? Mention it here! title: "" labels: "feature" assignees: "" @@ -8,8 +8,5 @@ assignees: "" ### Describe the feature request -_What is the feature of interest? Be clear and concise._ - -### Additional context/details - -_Provide any additional context or details here. What needs to be done, why, etc:_ +Please describe what behaviour you are looking for, the motivation for it, and use cases for where this feature would be helpful. +Try to be clear and concise - more details are usually helpful, but don't ramble on too much. diff --git a/.github/ISSUE_TEMPLATE/packaging.md b/.github/ISSUE_TEMPLATE/packaging.md new file mode 100644 index 00000000..3a13b560 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/packaging.md @@ -0,0 +1,13 @@ +--- +name: Packaging +about: For any issues, questions, or requests regarding packaging or distribution. +title: "" +labels: "packaging" +assignees: "" +--- + +## Details + +What is the issue? Please be clear and concise. + +Note: if this issue is about supporting a new package manager/installation method, please do consider maintaining it yourself and sending in a PR, and I'll be glad accept it! See [the documentation](https://clementtsang.github.io/bottom/contribution/packaging-and-distribution/) for more information. diff --git a/.github/ISSUE_TEMPLATE/packaging_template.md b/.github/ISSUE_TEMPLATE/packaging_template.md deleted file mode 100644 index 9a657c69..00000000 --- a/.github/ISSUE_TEMPLATE/packaging_template.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: Packaging -about: For any issues, questions, or requests regarding packaging or distribution. -title: "" -labels: "packaging" -assignees: "" ---- - -## Details - -_What is the issue? Please be clear and concise._ - -_Note: if this issue is about supporting a new package manager, please do consider maintaining it yourself and sending in a PR, and I'll be glad accept it! While I definitely want to support more ways of distribution, it gets quite challenging to support package managers for operating systems you don't even have installed..._ diff --git a/.github/ISSUE_TEMPLATE/question_template.md b/.github/ISSUE_TEMPLATE/questions.md index 67578f08..8e908c0f 100644 --- a/.github/ISSUE_TEMPLATE/question_template.md +++ b/.github/ISSUE_TEMPLATE/questions.md @@ -8,4 +8,4 @@ assignees: "" ### Question -_What do you want to ask in regards to this project? Note that if this is a feature request or a bug/issue report, please use the appropriate templates instead._ +What do you want to ask in regards to this project? Note that this is **not** the template to use if you have a bug report or feature request - use the appropriate templates instead. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 16a03ae8..9d07b495 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -24,6 +24,6 @@ _If relevant, ensure the following have been met:_ - [ ] _Areas your change affects have been linted using rustfmt (`cargo fmt`)_ - [ ] _The change has been tested and doesn't appear to cause any unintended breakage_ -- [ ] _Documentation has been added/updated if needed (README, help menu, etc.)_ +- [ ] _Documentation has been added/updated if needed (`README.md`, help menu, etc.)_ - [ ] _The pull request passes the provided CI pipeline_ - [ ] _There are no merge conflicts_ diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..67d6c829 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,27 @@ +name: docs +on: + workflow_dispatch: + # inputs: + # version: + # description: "The documentation version to update. Defaults to nightly." + # default: "nightly" + # required: false + push: + branches: + - master + paths: + - 'docs/**' + - '.github/workflows/docs.yml' +jobs: + build-documentation: + name: Build and deploy docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: 3.x + - run: pip install mkdocs-material + - run: pip install mdx_truly_sane_lists + - run: cd docs/ + - run: mkdocs gh-deploy --force diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 4c642504..d78f4767 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -11,6 +11,7 @@ on: isMock: description: "Mock nightly run, fill in with anything to trigger a mock build." default: "" + required: false jobs: create-github-release: @@ -31,3 +31,6 @@ deny.toml # vscode .vscode + +# mkdocs +site/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01d3157e..0336185b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,73 +1,30 @@ # Contribution -If you want to contribute to this project - first of all, thank you! I'm glad to see interest in it! +Contribution in any way is appreciated, whether it is reporting problems, fixing bugs, implementing features, improving the documentation, etc. -Here are some notes about how to contribute to bottom (structure is based on the official -[Rust contribution guidelines](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md)): +## Opening an issue -- [Feature reports](#feature-reports) -- [Bug reports](#bug-reports) -- [Other types of reports](#other-types-of-reports) -- [Pull requests](#pull-requests) +### Bug reports -## Feature reports +When filing a bug report, please use the [bug report template](https://github.com/ClementTsang/bottom/issues/new?assignees=&labels=bug&template=bug_report.md&title=) and fill in as much as you can. It is _incredibly_ difficult for a maintainer to fix +a bug when it cannot be reproduced, and giving as much detail as possible generally helps to make it easier to reproduce the problem! -Feature suggestions can be submitted using the "feature" tag. Prior to submission, please look to see if this has already been suggested or solved; if it has and is not resolved, it would be better to comment on the relevant report. +### Feature requests -Within your feature report, try to answer the given prompts - in particular, state the specific feature you want and if possible, please state why you want this added to the program. - -## Bug reports - -Bug reports can be submitted using the "bug" tag. Prior to submission, please look to see if this has already been reported or solved; if it has and is not resolved, it would be better to comment on the relevant report. - -Within your bug report, try to answer the given prompts. Be as specific as possible - describe your bug to the best of your ability, how to replicate it, and provide information like screenshots, OS and terminal. It can be very useful to help whoever is dealing with the issue! - -## Other types of reports - -For reports/suggestions that don't fit the definition of a feature or bug, try to use the other tags: - -- `documentation`: If you note a typo, or want to suggest something to do with the documentation of bottom, use this. -- `question`: If you have a question, and not really a suggestion or request, then use this tag. -- `ci`, `investigative`, `refactoring`: Generally, these are for internal use to track issues in order to manage GitHub Projects, and won't be the appropriate topic for a report. -- `other`: If your suggestion or issue doesn't fit those categories, then use this. +Please use the [feature request template](https://github.com/ClementTsang/bottom/issues/new?assignees=&labels=feature&template=feature_request.md&title=) and fill it out. Remember to give details about what the feature is along with why you think this suggestion will be useful. ## Pull requests -If you want to help contribute by submitting a PR, by all means, I'm open! In regards to the development process: - -- I develop primarily using _stable_ Rust. That is, whatever is the most up-to-date stable version you can get via running - `rustup update stable`. - -- There are some tests, they're mostly for sanity checks. Please run `cargo test` to ensure you didn't break anything important, unless the change will break the test (in which case please amend the tests). - - - Note that `cargo test` will fail on anything lower than 1.43.0 due to it using a then-introduced env variable. - -- I use both [clippy](https://github.com/rust-lang/rust-clippy) and [rustfmt](https://github.com/rust-lang/rustfmt) in development (with some settings, see [clippy.toml](./clippy.toml) and [rustfmt.toml](rustfmt.toml)). Note clippy must pass to for PRs to be accepted. - - - You can check clippy using `cargo clippy`. - - - I use [cargo-husky](https://github.com/rhysd/cargo-husky) to automatically run a `cargo clippy` check. - -- You may notice that I have fern and log as dependencies; this is mostly for easy debugging via the `debug!()` macro. It writes to the `debug.log` file that will automatically be created if you run in debug mode (so `cargo run`). - -And in regards to the pull request process: - -- Create a personal fork of the process and PR that, as per the [fork and pull method](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-collaborative-development-models). - -- Merge against the `master` branch. - -- If you encounter a merge conflict, I expect you to resolve this via rebasing to `master`. - -- _Ensure your change builds, runs, and works_. Furthermore, state how you checked this, including what platforms you tested on. - -- If your change will result in needing to update documentation, please do so. In particular: - - - Does the README need to be updated to accommodate your change? - - - Does the help action, `?`, need to be updated to accommodate your change? +The expected workflow for a pull request is: -- Please ensure that CI passes. If it fails, check to see why it fails! Chances are it's clippy. +1. Fork the project. +2. Make your changes. +3. Make any documentation changes if necessary - if you add a new feature, it'll probably need documentation changes. See [here](./documentation.md) for tips on documentation. +4. Commit and create a pull request to merge into the `master` branch. **Please follow the pull request template**. +5. Wait for the tests to pass. These consist of clippy lints, rustfmt checks, and basic tests. **If you are a first time contributor, you may need to skip this step for now, as GitHub Actions requires approval to run.** +6. Ask a maintainer to review your pull request. If changes are suggested or any comments are made, they should probably be addressed. Once it looks good, it'll be merged! -- If all looks good, then request someone with write access (so basically me, [@ClementTsang](https://github.com/ClementTsang)) to give your code a review. If it's fine, then I'll merge! +## Further reading -- Please use the [pull request template](https://github.com/ClementTsang/bottom/blob/master/.github/pull_request_template.md) to help you. +- For details on contributing to documentation, see [here](https://clementtsang.github.io/bottom/contribution/documentation/). +- For details on packaging and distribution, see [here](https://clementtsang.github.io/bottom/contribution/packaging-and-distribution/). diff --git a/FAQ.md b/FAQ.md deleted file mode 100644 index 8edc6858..00000000 --- a/FAQ.md +++ /dev/null @@ -1,18 +0,0 @@ -# FAQ - -- [My graphs look kinda weird with some extra dots, how do I fix this?](#braille-support) - -<h3 name="braille-support"> -My graphs look kinda weird with some extra dots, how do I fix this? -</h3> - - - -You'll have to make sure you have proper braille font support. For example, for Arch, you may have to -install ttf-ubraille and/or properly set it up for your terminal. - -- [Why can't I see all my processes/process usage on macOS?] - -You may have to run the program with elevated privileges - i.e. `sudo btm`. If you don't like doing -this repeatedly, you can manually force it to run with root each time - for example, following -[this related guide from the htop wiki](https://github.com/hishamhm/htop/wiki/macOS:-run-without-sudo). @@ -1,136 +1,68 @@ # bottom - -[](https://crates.io/crates/bottom) +[<img src="https://img.shields.io/github/workflow/status/ClementTsang/bottom/ci/master?style=flat-square&logo=github" alt="CI status">](https://github.com/ClementTsang/bottom/actions?query=branch%3Amaster) +[<img src="https://img.shields.io/crates/v/bottom.svg?style=flat-square" alt="crates.io">](https://crates.io/crates/bottom) +[<img src="https://img.shields.io/badge/documentation-bottom-66c2a5?style=flat-square&labelColor=555555&logoColor=white" alt="documentation">](https://clementtsang.github.io/bottom) A cross-platform graphical process/system monitor with a customizable interface and a multitude of features. Supports Linux, macOS, and Windows. Inspired by [gtop](https://github.com/aksakalli/gtop), [gotop](https://github.com/xxxserxxx/gotop), and [htop](https://github.com/htop-dev/htop/). - _Theme based on [gruvbox](https://github.com/morhetz/gruvbox)_ (`--color gruvbox`). _Font is [IBM Plex Mono](https://www.ibm.com/plex/), terminal is [Kitty](https://sw.kovidgoyal.net/kitty/)._ - -**Note**: If you are reading this on the master branch, then it may refer to in-development or un-released features/changes. Please refer to [release branch](https://github.com/ClementTsang/bottom/tree/release/README.md) or [crates.io](https://crates.io/crates/bottom) for the most up-to-date _release_ documentation. - -## Table of Contents - -- [Support](#support) - - [Compatibility](#compatibility) - - [Other known platform-specific issues](#other-known-platform-specific-issues) -- [Installation](#installation) - - [Manually](#manually) - - [Nightly](#nightly) - - [Cargo](#cargo) - - [AUR](#aur) - - [Debian](#debian) - - [Fedora/CentOS](#fedoracentos) - - [Gentoo](#gentoo) - - [Nix](#nix) - - [Solus](#solus) - - [MacPorts](#macports) - - [Homebrew](#homebrew) - - [Scoop](#scoop) - - [Chocolatey](#chocolatey) - - [winget](#winget) - - [Auto-completion](#auto-completion) -- [Usage](#usage) - - [Flags](#flags) - - [Keybindings](#keybindings) - - [General](#general) - - [Process bindings](#process-bindings) - - [Process search bindings](#process-search-bindings) - - [Process sort bindings](#process-sort-bindings) - - [Battery bindings](#battery-bindings) - - [Basic memory bindings](#basic-memory-bindings) - - [Process searching keywords](#process-searching-keywords) - - [Supported search types](#supported-search-types) - - [Supported comparison operators](#supported-comparison-operators) - - [Supported logical operators](#supported-logical-operators) - - [Supported units](#supported-units) - - [Other syntax](#other-syntax) - - [Mousebindings](#mousebindings) - - [General](#general-1) - - [CPU bindings](#cpu-bindings) - - [Process bindings](#process-bindings-1) -- [Features](#features) - - [Processes](#processes) - - [Process searching](#process-searching) - - [Process sorting](#process-sorting) - - [Tree mode](#tree-mode) - - [Zoom](#zoom) - - [Expand](#expand) - - [Basic mode](#basic-mode) - - [Config files](#config-files) - - [Config flags](#config-flags) - - [Theming](#theming) - - [Layout](#layout) - - [Disk, temperature, and network filtering](#disk-temperature-and-network-filtering) - - [Battery](#battery) -- [FAQ](#faq) -- [Contribution |