| Name | monoqueue JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | |
| Summary | Fight burnout. Stay organized. |
| upload_time | 2023-06-23 21:43:39 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | The Unlicense |
| keywords |
support
queue
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Monoqueue
*Fight burnout. Stay organized.*
## Purpose
This project unifies your support queue across various sources, such as:
* GitHub issues and PRs
* Topics from online forums
* Tickets from helpdesk software
* Any action that can be represented by a URL
Monoqueue's target audience is people managing large numbers of action items:
* Maintainers of open source software projects
* Support personnel on public community forums
* Anyone with more action items than they can finish
Items in the queue are scored according to a customizable ruleset, so that
you can attack them in order, maximizing the impact of your time and effort,
while minimizing decision paralysis and fatigue from repeated evaluation of
which items to address next.
It is designed to scale as your list of items becomes more than one person can
possibly handle completely. Rather than succumbing to Sisyphean ennui, define
your scoring criteria, let monoqueue sort your items, and do what you can!
You're only human; use monoqueue to be your best within a limited time budget.
## Design goals
* Efficient
* [Choice-minimal](https://tim.blog/2008/02/06/the-choice-minimal-lifestyle-6-formulas-for-more-output-and-less-overwhelm/)
* Impact maximizing
* [Open source](UNLICENSE)
* Scriptable
## Installation
```shell
pip install monoqueue
```
Or from source:
```shell
pip install --user git+https://github.com/ctrueden/monoqueue.git#egg=monoqueue
```
And put `~/.local/bin` on your path.
## Configuration
```shell
vi ~/.config/monoqueue.conf
```
Then add content of the form:
```ini
[rules]
rule01 = bookmark -> +20: action bookmark
rule10 = issue/pull_request -> +20: pull request
rule11 = "ctrueden" in issue/assignees/login -> +5: assigned to me
rule12 = ["ctrueden"] == issue/assignees/login -> +5: assigned to only me
rule13 = "/monoqueue/" in issue/url -> +5: favorite project (monoqueue)
rule14 = issue/milestone/title == "next-release" -> +3: next-release milestone
rule15 = "@ctrueden" in issue/body -> +2: mentions me
rule16 = issue/author_association == "CONTRIBUTOR" -> +5: issue author is non-member
rule17 = issue/state == "open" -> +1: open issue
rule18 = issue/reactions/total_count -> +X: number of reactions
rule19 = issue/comments -> +X: number of comments
rule20 = issue/draft -> -2: draft PR
rule50 = topic/has_accepted_answer is False -> +5: has no accepted answer
rule51 = "monoqueue" in topic/tags -> +5: monoqueue tag
# 10 min = +12960; 1 hour = +2160; 8 hours = +270; 1 day = +90; 1 week = +10; 2 weeks = +5; 1 month = +2
rule77 = 7776000 / seconds_since_update -> +X: time since last update (rapid response)
#rule77 = seconds_since_update / 86400 -> +X: days since last update (backlog tackle)
rule99 = issue/milestone/title == "unscheduled" -> /100: unscheduled milestone
[firefox]
folder = ACTION
[github]
token = <your-github-api-token>
query = is:open+org:my-favorite-org+org:my-other-favorite-org+repo:a-repo-I-manage
[forum.example.com]
handler = discourse
username = <your-discourse-username-on-forum.example.com>
key = <discourse-api-key-for-forum.example.com>
query = #a-category-to-search tags:foo,bar,stuff status:open status:unsolved
```
Then protect your secrets:
```shell
chmod 600 ~/.config/monoqueue.conf
```
### Rules
Rules are written in Python syntax, parsed by Python's `ast` module, and evaluated
using a custom evaluator to avoid calling the insecure `eval` function. The monoqueue
evaluator supports standard Python unary and binary operators, as well as a special
overload of the divide (`/`) operator for digging into nested data structures easily.
To figure out your rules, first set up your [sources](#sources), then run `mq up`,
then browse your monoqueue data in `~/.local/share/monoqueue/items.json` while
studying the rules above for inspiration. You can do it, I believe in you! <3
### Sources
Apart from the `[rules]`, each configuration section declares a source.
#### Firefox
The Firefox handler scans your local Firefox installation's bookmarks, and
creates an action item for each item within any folder whose name regex-matches
the configured one.
#### GitHub
The GitHub handler connects to GitHub using the specified personal access token,
and pulls down all GitHub Issues (including Pull Requests) matching the given query.
How to make a personal access token:
- https://github.com/settings/tokens → Generate new token → Generate new token (classic)
- Name the token whatever you want, use whatever expiration you want
- Scope: repo (Full control of private repositories)
- Click green "Generate token" button
- Copy the resulting token to your clipboard
- Paste it into `~/.config/monoqueue.conf`
as a `token = <your-token>` pair in a `[github]` section.
#### Discourse
The Discourse handler connects to a Discourse forum instance via its API using
the specified API key.
How to make a Discourse API key:
- https://forum.yourdiscourseinstance.com/admin/api/keys → New API Key
- Description: monoqueue (or whatever you want)
- User Level: Single User (your username)
- Scope: Read-only
- Click the blue "Save" button
- Copy the resulting key to your clipboard
- Paste it into `~/.config/monoqueue.conf`
as an `key = <your-api-key>` pair in the relevant Discourse section.
- Also add a `username = <your-username>` pair to that same section.
## Usage
Command | Description
-----------------|------------
`mq up` | Fetch items from configured sources (Firefox, GitHub, Discourse, etc.).
`mq ui` | Launch the interactive user interface.
`mq ls` | List action items in plaintext.
`mq ls --html` | List action items as an HTML report.
`mq info <url>` | Show detailed info about an action item.
## Limitations and pitfalls
> Well am I making haste or could it be haste is making me?
> What's time but a thing to kill or keep or buy or lose or live in?
> I gotta go faster, keep up the pace
> Just to stay in the human race
—Bad Religion - [Supersonic](https://youtu.be/D0RKVCH6O0o)
* [Learn to say no sometimes](https://jamesclear.com/saying-no).
* [Taking breaks effectively is tricky](https://www.personneltoday.com/hr/breaks-from-work-mental-fatigue-study/)
* [Campbell's Law](https://en.wikipedia.org/wiki/Campbell%27s_law)
Raw data
{
"_id": null,
"home_page": "",
"name": "monoqueue",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "support,queue",
"author": "",
"author_email": "Curtis Rueden <ctrueden@wisc.edu>",
"download_url": "https://files.pythonhosted.org/packages/b8/fb/c309191c71930a230591dd6126506177cab539ed74dd292d377e5db93fa2/monoqueue-1.1.0.tar.gz",
"platform": null,
"description": "# Monoqueue\n\n*Fight burnout. Stay organized.*\n\n## Purpose\n\nThis project unifies your support queue across various sources, such as:\n\n* GitHub issues and PRs\n* Topics from online forums\n* Tickets from helpdesk software\n* Any action that can be represented by a URL\n\nMonoqueue's target audience is people managing large numbers of action items:\n\n* Maintainers of open source software projects\n* Support personnel on public community forums\n* Anyone with more action items than they can finish\n\nItems in the queue are scored according to a customizable ruleset, so that\nyou can attack them in order, maximizing the impact of your time and effort,\nwhile minimizing decision paralysis and fatigue from repeated evaluation of\nwhich items to address next.\n\nIt is designed to scale as your list of items becomes more than one person can\npossibly handle completely. Rather than succumbing to Sisyphean ennui, define\nyour scoring criteria, let monoqueue sort your items, and do what you can!\n\nYou're only human; use monoqueue to be your best within a limited time budget.\n\n## Design goals\n\n* Efficient\n* [Choice-minimal](https://tim.blog/2008/02/06/the-choice-minimal-lifestyle-6-formulas-for-more-output-and-less-overwhelm/)\n* Impact maximizing\n* [Open source](UNLICENSE)\n* Scriptable\n\n## Installation\n\n```shell\npip install monoqueue\n```\n\nOr from source:\n\n```shell\npip install --user git+https://github.com/ctrueden/monoqueue.git#egg=monoqueue\n```\n\nAnd put `~/.local/bin` on your path.\n\n## Configuration\n\n```shell\nvi ~/.config/monoqueue.conf\n```\n\nThen add content of the form:\n\n```ini\n[rules]\nrule01 = bookmark -> +20: action bookmark\n\nrule10 = issue/pull_request -> +20: pull request\nrule11 = \"ctrueden\" in issue/assignees/login -> +5: assigned to me\nrule12 = [\"ctrueden\"] == issue/assignees/login -> +5: assigned to only me\nrule13 = \"/monoqueue/\" in issue/url -> +5: favorite project (monoqueue)\nrule14 = issue/milestone/title == \"next-release\" -> +3: next-release milestone\nrule15 = \"@ctrueden\" in issue/body -> +2: mentions me\nrule16 = issue/author_association == \"CONTRIBUTOR\" -> +5: issue author is non-member\nrule17 = issue/state == \"open\" -> +1: open issue\nrule18 = issue/reactions/total_count -> +X: number of reactions\nrule19 = issue/comments -> +X: number of comments\nrule20 = issue/draft -> -2: draft PR\n\nrule50 = topic/has_accepted_answer is False -> +5: has no accepted answer\nrule51 = \"monoqueue\" in topic/tags -> +5: monoqueue tag\n\n# 10 min = +12960; 1 hour = +2160; 8 hours = +270; 1 day = +90; 1 week = +10; 2 weeks = +5; 1 month = +2\nrule77 = 7776000 / seconds_since_update -> +X: time since last update (rapid response)\n#rule77 = seconds_since_update / 86400 -> +X: days since last update (backlog tackle)\n\nrule99 = issue/milestone/title == \"unscheduled\" -> /100: unscheduled milestone\n\n[firefox]\nfolder = ACTION\n\n[github]\ntoken = <your-github-api-token>\nquery = is:open+org:my-favorite-org+org:my-other-favorite-org+repo:a-repo-I-manage\n\n[forum.example.com]\nhandler = discourse\nusername = <your-discourse-username-on-forum.example.com>\nkey = <discourse-api-key-for-forum.example.com>\nquery = #a-category-to-search tags:foo,bar,stuff status:open status:unsolved\n```\n\nThen protect your secrets:\n\n```shell\nchmod 600 ~/.config/monoqueue.conf\n```\n\n### Rules\n\nRules are written in Python syntax, parsed by Python's `ast` module, and evaluated\nusing a custom evaluator to avoid calling the insecure `eval` function. The monoqueue\nevaluator supports standard Python unary and binary operators, as well as a special\noverload of the divide (`/`) operator for digging into nested data structures easily.\n\nTo figure out your rules, first set up your [sources](#sources), then run `mq up`,\nthen browse your monoqueue data in `~/.local/share/monoqueue/items.json` while\nstudying the rules above for inspiration. You can do it, I believe in you! <3\n\n### Sources\n\nApart from the `[rules]`, each configuration section declares a source.\n\n#### Firefox\n\nThe Firefox handler scans your local Firefox installation's bookmarks, and\ncreates an action item for each item within any folder whose name regex-matches\nthe configured one.\n\n#### GitHub\n\nThe GitHub handler connects to GitHub using the specified personal access token,\nand pulls down all GitHub Issues (including Pull Requests) matching the given query.\n\nHow to make a personal access token:\n- https://github.com/settings/tokens → Generate new token → Generate new token (classic)\n- Name the token whatever you want, use whatever expiration you want\n- Scope: repo (Full control of private repositories)\n- Click green \"Generate token\" button\n- Copy the resulting token to your clipboard\n- Paste it into `~/.config/monoqueue.conf`\n as a `token = <your-token>` pair in a `[github]` section.\n\n#### Discourse\n\nThe Discourse handler connects to a Discourse forum instance via its API using\nthe specified API key.\n\nHow to make a Discourse API key:\n- https://forum.yourdiscourseinstance.com/admin/api/keys → New API Key\n- Description: monoqueue (or whatever you want)\n- User Level: Single User (your username)\n- Scope: Read-only\n- Click the blue \"Save\" button\n- Copy the resulting key to your clipboard\n- Paste it into `~/.config/monoqueue.conf`\n as an `key = <your-api-key>` pair in the relevant Discourse section.\n- Also add a `username = <your-username>` pair to that same section.\n\n## Usage\n\nCommand | Description\n-----------------|------------\n`mq up` | Fetch items from configured sources (Firefox, GitHub, Discourse, etc.).\n`mq ui` | Launch the interactive user interface.\n`mq ls` | List action items in plaintext.\n`mq ls --html` | List action items as an HTML report.\n`mq info <url>` | Show detailed info about an action item.\n\n## Limitations and pitfalls\n\n> Well am I making haste or could it be haste is making me? \n> What's time but a thing to kill or keep or buy or lose or live in? \n> I gotta go faster, keep up the pace \n> Just to stay in the human race\n\n—Bad Religion - [Supersonic](https://youtu.be/D0RKVCH6O0o)\n\n* [Learn to say no sometimes](https://jamesclear.com/saying-no).\n* [Taking breaks effectively is tricky](https://www.personneltoday.com/hr/breaks-from-work-mental-fatigue-study/)\n* [Campbell's Law](https://en.wikipedia.org/wiki/Campbell%27s_law)\n",
"bugtrack_url": null,
"license": "The Unlicense",
"summary": "Fight burnout. Stay organized.",
"version": "1.1.0",
"project_urls": {
"documentation": "https://github.com/ctrueden/monoqueue/blob/main/README.md",
"download": "https://pypi.org/project/monoqueue/",
"homepage": "https://github.com/ctrueden/monoqueue",
"source": "https://github.com/ctrueden/monoqueue",
"tracker": "https://github.com/ctrueden/monoqueue/issues"
},
"split_keywords": [
"support",
"queue"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c1ec9632ca9e21fdcf7332346dd2afb25697f8732bb663d8b892228e22db0332",
"md5": "b616b0298292b03b0faceded7254535f",
"sha256": "81d1492565bbe895ca6187b2c48f8230c14d8c1e2c15606feb1d8739c5fc1275"
},
"downloads": -1,
"filename": "monoqueue-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b616b0298292b03b0faceded7254535f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 19175,
"upload_time": "2023-06-23T21:43:35",
"upload_time_iso_8601": "2023-06-23T21:43:35.782754Z",
"url": "https://files.pythonhosted.org/packages/c1/ec/9632ca9e21fdcf7332346dd2afb25697f8732bb663d8b892228e22db0332/monoqueue-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8fbc309191c71930a230591dd6126506177cab539ed74dd292d377e5db93fa2",
"md5": "160df1899ca2291e21b2e0db7ccee327",
"sha256": "c1f7d22bed8224a1b40443befb6ab448fdcc1c1d7e2121f15dc58a7713983d6b"
},
"downloads": -1,
"filename": "monoqueue-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "160df1899ca2291e21b2e0db7ccee327",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19323,
"upload_time": "2023-06-23T21:43:39",
"upload_time_iso_8601": "2023-06-23T21:43:39.642366Z",
"url": "https://files.pythonhosted.org/packages/b8/fb/c309191c71930a230591dd6126506177cab539ed74dd292d377e5db93fa2/monoqueue-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-23 21:43:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ctrueden",
"github_project": "monoqueue",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "monoqueue"
}
