diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/interfaces.md | 66 | ||||
| -rw-r--r-- | doc/usage/query-language.md | 167 | ||||
| -rw-r--r-- | doc/usage/third-party.md | 113 | ||||
| -rw-r--r-- | doc/usage/workflows.md | 62 |
4 files changed, 408 insertions, 0 deletions
diff --git a/doc/usage/interfaces.md b/doc/usage/interfaces.md new file mode 100644 index 00000000..9df342c3 --- /dev/null +++ b/doc/usage/interfaces.md @@ -0,0 +1,66 @@ +# Native interfaces + +This page provides an overview of the different interfaces `git-bug` supports. + +<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 --> + +- [TUI](#tui) +- [Web UI](#web-ui) + +<!-- mdformat-toc end --> + +## TUI<a name="tui"></a> + +The integrated TUI (text-based user interface) is the recommended way to +interface with `git-bug` issues in your repository. + +To start it, run `git bug termui` in your terminal. + + + +## Web UI<a name="web-ui"></a> + +The web UI is packed inside the same binary and serves static content through an +http server running on the local machine. The frontend interacts with the +backend through a GraphQL API. [View the schema][gql-schema] for more +information. + +To serve the website locally, run `git bug webui` in your terminal. + +> [!NOTE] +> The web interface is alpha-level software and does not support all of the +> features of `git-bug`. We recommend using the TUI for most day-to-day +> operations at the moment. + +<details> +<summary><strong>View the issue feed</strong></summary> +<center> <img + alt="An example of viewing the issue feed in the web interface" + src="../assets/web-screenshot-feed.png" + width="880" +/></center> +</details> + +<details> +<summary><strong>View the discussion for an issue</strong></summary> +<center><img + alt="An example of viewing the discussion for an issue in the web interface" + src="../assets/web-screenshot-comments.png" + width="880" +/></center> +</details> + +______________________________________________________________________ + +##### See more + +- [Filtering query results][docs/usage/filter] +- [How to use bridges][docs/usage/bridges] +- [Understanding the workflow models][docs/usage/workflows] +- :house: [Documentation home][docs/home] + +[docs/home]: ../README.md +[docs/usage/bridges]: ./third-party.md +[docs/usage/filter]: ./query-language.md +[docs/usage/workflows]: ./workflows.md +[gql-schema]: ../../api/graphql/schema diff --git a/doc/usage/query-language.md b/doc/usage/query-language.md new file mode 100644 index 00000000..c513e0b0 --- /dev/null +++ b/doc/usage/query-language.md @@ -0,0 +1,167 @@ +# Search filters + +When performing a search (e.g. listing issues), you can use different qualifiers +to narrow the results. This page provides an overview of these filters, and how +to use them. + +<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 --> + +- [Overview](#overview) +- [Filtering](#filtering) + - [Filtering by status](#filtering-by-status) + - [Filtering by author](#filtering-by-author) + - [Filtering by participant](#filtering-by-participant) + - [Filtering by actor](#filtering-by-actor) + - [Filtering by label](#filtering-by-label) + - [Filtering by title](#filtering-by-title) + - [Filtering by missing feature](#filtering-by-missing-feature) +- [Sorting](#sorting) + - [Sort by Id](#sort-by-id) + - [Sort by Creation time](#sort-by-creation-time) + - [Sort by Edit time](#sort-by-edit-time) + +<!-- mdformat-toc end --> + +## Overview<a name="overview"></a> + +The query filters in `git-bug` have a familiar look and feel: + +``` +status:open sort:edit +``` + +**Key things to know** + +- All queries are case insensitive +- You can combine as many qualifiers as you want +- If you have a space in your qualifier, be sure to wrap it in double quotes. As + an example, `author:"René Descartes"` would filter for issues opened by + `René Descartes`, whereas `author:René Descartes` filter for `René` as the + author and return issues that contain `Descartes` somewhere in the title, + description, or comments. +- Instead of a complete ID, you can use any prefix length, as long as it is long + enough to be unique (similar to git commit hashes). For example, + `participant=9ed1a` would match against participants with an ID of + `9ed1af428...` and `9ed1ae24a...` + +## Filtering<a name="filtering"></a> + +### Filtering by status<a name="filtering-by-status"></a> + +You can filter bugs based on their status. + +| Qualifier | Example | +| --------------- | ----------------------------------- | +| `status:open` | `status:open` matches open bugs | +| `status:closed` | `status:closed` matches closed bugs | + +### Filtering by author<a name="filtering-by-author"></a> + +You can filter based on the person who opened the bug. + +| Qualifier | Example | +| -------------- | -------------------------------------------------------------------------------- | +| `author:QUERY` | `author:descartes` matches bugs opened by `René Descartes` or `Robert Descartes` | +| | `author:"rené descartes"` matches bugs opened by `René Descartes` | + +### Filtering by participant<a name="filtering-by-participant"></a> + +You can filter based on the person who participated in any activity related to +the bug (opened bug or added a comment). + +| Qualifier | Example | +| ------------------- | -------------------------------------------------------------------------------------------------- | +| `participant:QUERY` | `participant:descartes` matches bugs opened or commented by `René Descartes` or `Robert Descartes` | +| | `participant:"rené descartes"` matches bugs opened or commented by `René Descartes` | + +### Filtering by actor<a name="filtering-by-actor"></a> + +You can filter based on the person who interacted with the bug. + +| Qualifier | Example | +| ------------- | ------------------------------------------------------------------------------- | +| `actor:QUERY` | `actor:descartes` matches bugs edited by `René Descartes` or `Robert Descartes` | +| | `actor:"rené descartes"` matches bugs edited by `René Descartes` | + +> [!NOTE] +> Interactions with issues include opening the bug, adding comments, adding or +> removing labels, etc. + +### Filtering by label<a name="filtering-by-label"></a> + +You can filter based on the bug's label. + +| Qualifier | Example | +| ------------- | ------------------------------------------------------------------------- | +| `label:LABEL` | `label:prod` matches bugs with the label `prod` | +| | `label:"Good first issue"` matches bugs with the label `Good first issue` | + +### Filtering by title<a name="filtering-by-title"></a> + +You can filter based on the bug's title. + +| Qualifier | Example | +| ------------- | ------------------------------------------------------------------------------ | +| `title:TITLE` | `title:Critical` matches bugs with a title containing `Critical` | +| | `title:"Typo in string"` matches bugs with a title containing `Typo in string` | + +### Filtering by missing feature<a name="filtering-by-missing-feature"></a> + +You can filter bugs based on the absence of something. + +| Qualifier | Example | +| ---------- | -------------------------------------- | +| `no:label` | `no:label` matches bugs with no labels | + +## Sorting<a name="sorting"></a> + +You can sort results by adding a `sort:` qualifier to your query. “Descending” +means most recent time or largest ID first, whereas “Ascending” means oldest +time or smallest ID first. + +Note: to deal with differently-set clocks on distributed computers, `git-bug` +uses a logical clock internally rather than timestamps to order bug changes over +time. That means that the timestamps recorded might not match the returned +ordering. To learn more, we encourage you to read about why +[time is unreliable][docs/design/model]. + +### Sort by Id<a name="sort-by-id"></a> + +| Qualifier | Example | +| -------------------------- | ----------------------------------------------------- | +| `sort:id-desc` | `sort:id-desc` will sort bugs by their descending Ids | +| `sort:id` or `sort:id-asc` | `sort:id` will sort bugs by their ascending Ids | + +### Sort by Creation time<a name="sort-by-creation-time"></a> + +You can sort bugs by their creation time. + +| Qualifier | Example | +| --------------------------------------- | ------------------------------------------------------------------- | +| `sort:creation` or `sort:creation-desc` | `sort:creation` will sort bugs by their descending creation time | +| `sort:creation-asc` | `sort:creation-asc` will sort bugs by their ascending creation time | + +### Sort by Edit time<a name="sort-by-edit-time"></a> + +You can sort bugs by their edit time. + +| Qualifier | Example | +| ------------------------------- | ------------------------------------------------------------------- | +| `sort:edit` or `sort:edit-desc` | `sort:edit` will sort bugs by their descending last edition time | +| `sort:edit-asc` | `sort:edit-asc` will sort bugs by their ascending last edition time | + +______________________________________________________________________ + +##### See more + +- [A description of the data model][docs/design/model] +- [How to use bridges][docs/usage/bridges] +- [Learn about the native interfaces][docs/usage/interfaces] +- [Understanding the workflow models][docs/usage/workflows] +- :house: [Documentation home][docs/home] + +[docs/design/model]: ../design/data-model.md#you-cant-rely-on-the-time-provided-by-other-people-their-clock-might-by-off-for-anything-other-than-just-display +[docs/home]: ../README.md +[docs/usage/bridges]: ./third-party.md +[docs/usage/interfaces]: ./interfaces.md +[docs/usage/workflows]: ./workflows.md diff --git a/doc/usage/third-party.md b/doc/usage/third-party.md new file mode 100644 index 00000000..39a09187 --- /dev/null +++ b/doc/usage/third-party.md @@ -0,0 +1,113 @@ +# Using third-party platforms via bridges<a name="using-bridges"></a> + +This page provides an overview of how to use _bridges_ to sync issues to and +from third-party platforms. + +<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 --> + +- [Overview](#overview) +- [Supported bridges](#supported-bridges) +- [Getting started](#getting-started) +- [Interacting with the bridge](#interacting-with-the-bridge) + +<!-- mdformat-toc end --> + +## Overview<a name="overview"></a> + +Bridges within `git-bug` are bi-directional, incremental, and speedy gateways to +third-party platforms. Configuring a bridge allows you to push and pull issues +to and from a third party platform. + +This expands the utility and function of `git-bug`: because issues are just +objects in your git repository, you can import issues from a bridge to work on +them in bulk, offline, in your preferred environment, at your own pace. When +you're ready to push your issues back to the external platform again, you'll be +able to synchronize the changes you made with one simple command. + +<p align="center"> + <img src="../assets/bridge-workflow.png" alt="Bridge workflow"> +</p> + +This has several benefits: + +- works offline, including edition +- browsing is pretty much instant +- you get to choose the UI you prefer between CLI, interactive TUI or in your + browser with the WEBUI +- you have a near-complete archive of issues locally, embedded in your git + repository, in case the external platform becomes inaccessible +- you are free to move to another platform -- your issues follow wherever your + repo goes! + +## Supported bridges<a name="supported-bridges"></a> + +We support a number of bridges: + +- Jira +- GitHub +- GitLab +- Launchpad + +_For a full list of the features enabled for each bridge, see the +[feature matrix][docs/feature-matrix]._ + +## Getting started<a name="getting-started"></a> + +1. From within a git repository, run `git bug bridge configure` to start the + configuration wizard +2. Choose the type of bridge you want to configure, e.g. `github` +3. Type a name for the bridge configuration. As you can configure multiple + bridges, this name will allow you to choose when there is an ambiguity. +4. If you already have a repository created on the external platform, and your + local git repository has that as a remote, the configuration wizard will + automatically detect the URL. Otherwise, please ensure you enter the + appropriate URL for the remote project: something like + `https://github.com/git-bug/git-bug` +5. Create an access token. You can either use the interactive token creation, + enter it on your own token, or use an existing token if you already have one + +That's it! Once you've completed the wizard, you'll have successfully configured +a bridge. + +## Interacting with the bridge<a name="interacting-with-the-bridge"></a> + +To push issues out to the bridge, run: + +```bash +git bug bridge push [NAME] +``` + +To pull and integrate updates for issues from the bridge: + +```bash +git bug bridge pull [NAME] +``` + +> [!TIP] +> See the [CLI documentation][doc/cli/bridge] for more information on the +> command line arguments and options. + +The command line is primarily meant for programmatic usage or to interface with +`git-bug` with scripts or other tools. For day to day usage, we recommend taking +a look at [the supported interfaces][docs/usage/interfaces], which include a +robust TUI and an in-progress Web UI. + +______________________________________________________________________ + +##### See more + +- [A bird's-eye view of the internal architecture][docs/design/arch] +- [A description of the data model][docs/design/model] +- [An overview of the native interfaces][docs/usage/interfaces] +- [Filtering query results][docs/usage/filter] +- [Understanding the workflow models][docs/usage/workflows] +- :house: [Documentation home][docs/home] + +[doc/cli/bridge]: ../md/git-bug_bridge.md +[docs/design/arch]: ../design/architecture.md +[docs/design/model]: ../design/data-model.md +[docs/feature-matrix]: ../feature-matrix.md +[docs/home]: ../README.md +[docs/usage/filter]: ./query-language.md +[docs/usage/interfaces]: ./interfaces.md +[docs/usage/workflows]: ./workflows.md diff --git a/doc/usage/workflows.md b/doc/usage/workflows.md new file mode 100644 index 00000000..50477847 --- /dev/null +++ b/doc/usage/workflows.md @@ -0,0 +1,62 @@ +# Workflows + +This document provides an overview of different workflows that `git-bug` +supports. + +<!-- mdformat-start --slug=github --maxlevel=4 --minlevel=2 --> + +## Native workflow + +<p align="center"> + <img src="../assets/native-workflow.png" alt="Native workflow"> +</p> + +This is the pure `git-bug` experience. In a similar fashion as with code, use +`git bug push` and `git bug pull` to push and pull your bugs between git remotes +and collaborate with your teammate. + +_Recommended reading: [CLI documentation][docs/cli]_ + +## Bridge workflow + +<p align="center"> + <img src="../assets/bridge-workflow.png" alt="Bridge workflow"> +</p> + +`git-bug` supports syncing issues with third-party platforms, such as GitHub, +GitLab, and Jira. This lets you work on issues offline, editing issues in bulk +with your preferred editor, or to build an archive of any project's issues -- +it's up to you! + +_Recommended reading: [How to use bridges][docs/usage/bridges]_ + +## Web UI workflow + +<p align="center"> + <img src="../assets/webui-workflow.png" alt="Web UI workflow"> +</p> + +> [!NOTE] +> The web UI is a work in progress, and is not feature-complete. To utilize +> `git-bug` to its full potential, we recommend using the TUI or CLI. + +Often, projects needs to have their bug-tracker public and accept editions from +anyone facing a problem. To support this workflow, `git-bug` aims to have the +web UI accept external OAuth authentication and act as a public portal. However +the web UI is not up to speed for that yet. Contributions are very much welcome! + +______________________________________________________________________ + +##### See also<a name="see-also"></a> + +- [CLI documentation][docs/cli] +- [Filtering query results][docs/usage/filter] +- [How to use bridges][docs/usage/bridges] +- [Learn about the native interfaces][docs/usage/interfaces] +- :house: [Documentation home][docs/home] + +[docs/cli]: ../md/git-bug.md +[docs/home]: ../README.md +[docs/usage/bridges]: ./third-party.md +[docs/usage/filter]: ./query-language.md +[docs/usage/interfaces]: ./interfaces.md |