Rework github project queries

- remove om-dash-github-project-cards - rename om-dash-github-topics back to om-dash-github - add :project and :project-status queries - support v2 and classic projects
gavv · Dec 3, 2024 · d1659f3 · d1659f3
1 parent c26bf0f
commit d1659f3
Show file tree

Hide file tree

Showing 2 changed files with 455 additions and 441 deletions.
diff --git a/README.org b/README.org
@@ -27,8 +27,7 @@ I wanted a tool that can give me a brief summary of all ongoing projects: what's
 
 om-dash implementats a few configurable dynamic blocks:
 
-- =om-dash-github-topics= - generates a table with issues or pull requests from github repository
-- =om-dash-github-project-cards= - generates a table with cards from github classic project
+- =om-dash-github= - generates a table with issues or pull requests from github repository
 - =om-dash-orgfile= - generates tables with top-level entries from an org file
 - =om-dash-imap= - generates table with unread email counters for IMAP folder
 - =om-dash-command= - generates a table from JSON or CSV output of a shell command
@@ -68,67 +67,49 @@ Screenshot of a project from "dashboard.org" described above:
 Display all open pull requests and pull requests closed last month.
 
 #+BEGIN_EXAMPLE
-,#+BEGIN: om-dash-github-topics :repo "roc-streaming/roc-toolkit" :type pullreq :open "*" :closed "-1mo"
+,#+BEGIN: om-dash-github :repo "roc-streaming/roc-toolkit" :type pullreq :open "*" :closed "-1mo"
 ...
 ,#+END:
 #+END_EXAMPLE
 
 [[./screenshot/github_pull_requests.png]]
 
-To filter github issues and pull requests, you can use either github search queries (with optional jq selector), or simple plist notation. See documentation below.
-
 *** Github issues
 
 Display all open issues except those which have "help wanted" label.
 
 #+BEGIN_EXAMPLE
-,#+BEGIN: om-dash-github-topics :repo "gavv/signal-estimator" :type issue :open "-label:\"help wanted\""
+,#+BEGIN: om-dash-github :repo "gavv/signal-estimator" :type issue :open (:no-label "help wanted")
 ...
 ,#+END:
 #+END_EXAMPLE
 
 [[./screenshot/github_issues.png]]
 
-To filter github issues and pull requests, you can use either github search queries (with optional jq selector), or simple plist notation. See documentation below.
-
-*** Github project items
-
-Display all items from github project v2 (non-clasic, a.k.a. beta) with project id "5", item type "Issue", and item status "In work".
-
-#+BEGIN_EXAMPLE
-,#+BEGIN: om-dash-github-project-items :owner "roc-streaming" :project 5 :type issue :status "In work"
-...
-,#+END:
-#+END_EXAMPLE
-
-[[./screenshot/github_project_items.png]]
-
-*** Github project cards (classic)
+*** Github project
 
-Display all cards from github classic project (now being officially deprecated by github, but still working) with project id "2", card type "issue", and column name "In work".
+Display all open issues from github project 5 with status (column) "In work".
 
 #+BEGIN_EXAMPLE
-,#+BEGIN: om-dash-github-project-cards :repo "roc-streaming/roc-toolkit" :project 2 :column "In work" :type issue :state open
+,#+BEGIN: om-dash-github :repo "roc-streaming/roc-toolkit" :type issue :open (:project 5 :project-status "In work")
 ...
 ,#+END:
 #+END_EXAMPLE
 
-[[./screenshot/github_project_cards.png]]
+[[./screenshot/github_project.png]]
 
 *** Tasks from org file
 
-Display 1-level TODO tasks as tables with their child 2-level TODO tasks as table rows. Hide 1-level DONE tasks.
+Display 1-level TODO tasks as tables with their child 2-level TODO tasks as table rows. Hide 1-level DONE tasks. Hide tasks with category "note".
 
 #+BEGIN_EXAMPLE
-,#+BEGIN: om-dash-orgfile :file "~/cloud/org/roc-toolkit.org" :query (:todo-depth 2 :done-depth 0)
+,#+BEGIN: om-dash-orgfile :file "~/cloud/org/roc-toolkit.org" :query (:todo-depth 2 :done-depth 0 :no-category "note")
 ...
 ,#+END:
 #+END_EXAMPLE
 
 [[./screenshot/orgfile_tasks.png]]
 
-To filter org tasks, you can use either org-ql sexp or string query, or simple plist notation. See documentation below.
-
 *** Unread email counters from IMAP
 
 Display new and unread email counters for IMAP directory tree.
@@ -337,30 +318,30 @@ the function updates all blocks inside 1.1, 1.1.1, 1.1.2.
 
 This section lists dynamic blocks implemented by =om-dash=. Each block named =om-dash-xxx= corresponds to a function named =org-dblock-write:om-dash-xxx=.
 
-#+BEGIN: om-dash--readme-symbol :symbol org-dblock-write:om-dash-github-topics
-*** om-dash-github-topics
+#+BEGIN: om-dash--readme-symbol :symbol org-dblock-write:om-dash-github
+*** om-dash-github
 Builds org heading with a table of github issues or pull requests.
 
 Basic example:
 
 #+BEGIN_EXAMPLE
-  ,#+BEGIN: om-dash-github-topics :repo "owner/repo" :type issue :open "*" :closed "-1w"
+  ,#+BEGIN: om-dash-github :repo "owner/repo" :type issue :open "*" :closed "-1w"
   ...
   ,#+END:
 #+END_EXAMPLE
 
 More complicated query using simple syntax:
 
 #+BEGIN_EXAMPLE
-  ,#+BEGIN: om-dash-github-topics :repo "owner/repo" :type pullreq :open (:milestone "1.2.3" :label "blocker" :no-label "triage")
+  ,#+BEGIN: om-dash-github :repo "owner/repo" :type pullreq :open (:milestone "1.2.3" :label "blocker" :no-label "triage")
   ...
   ,#+END:
 #+END_EXAMPLE
 
 Same query but by providing github search query and jq selector:
 
 #+BEGIN_EXAMPLE
-  ,#+BEGIN: om-dash-github-topics :repo "owner/repo" :type pullreq :open ("milestone:1.2.3 label:blocker" ".labels | (.name == \"triage\") | not")
+  ,#+BEGIN: om-dash-github :repo "owner/repo" :type pullreq :open ("milestone:1.2.3 label:blocker" ".labels | (.name == \"triage\") | not")
   ...
   ,#+END:
 #+END_EXAMPLE
@@ -414,24 +395,27 @@ Or you can use a single query regardless of topic state:
 =SIMPLE-QUERY= format is a convenient way to build queries for some typical
 use cases. The query should be a =plist= with the following properties:
 
-| property          | description                                             |
-|-------------------+---------------------------------------------------------|
-| :created-at       | include only topics created within given date range     |
-| :updated-at       | include only topics updated within given date range     |
-| :closed-at        | include only topics closed within given date range      |
-| :milestone        | include only topics with any of given milestone(s)      |
-| :no-milestone     | exclude topics with any of given milestone(s)           |
-| :label            | include only topics with any of given label(s)          |
-| :every-label      | include only topics with all of given label(s)          |
-| :no-label         | exclude topics with any of given label(s)               |
-| :author           | include only topics with any of given author(s)         |
-| :no-author        | exclude topics with any of given author(s)              |
-| :assignee         | include only topics with any of given assignee(s)       |
-| :no-assignee      | exclude topics with any of given assignee(s)            |
-| :reviewer         | include only topics with any of given reviewer(s)       |
-| :no-reviewer      | exclude topics with any of given reviewer(s)            |
-| :review-status    | include only topics with any of given review status(es) |
-| :no-review-status | exclude topics with any of given review status(es)      |
+| property           | description                                              |
+|--------------------+----------------------------------------------------------|
+| :created-at        | include only topics created within given date range      |
+| :updated-at        | include only topics updated within given date range      |
+| :closed-at         | include only topics closed within given date range       |
+| :milestone         | include only topics with any of given milestone(s)       |
+| :no-milestone      | exclude topics with any of given milestone(s)            |
+| :label             | include only topics with any of given label(s)           |
+| :every-label       | include only topics with all of given label(s)           |
+| :no-label          | exclude topics with any of given label(s)                |
+| :author            | include only topics with any of given author(s)          |
+| :no-author         | exclude topics with any of given author(s)               |
+| :assignee          | include only topics with any of given assignee(s)        |
+| :no-assignee       | exclude topics with any of given assignee(s)             |
+| :reviewer          | include only topics with any of given reviewer(s)        |
+| :no-reviewer       | exclude topics with any of given reviewer(s)             |
+| :review-status     | include only topics with any of given review status(es)  |
+| :no-review-status  | exclude topics with any of given review status(es)       |
+| :project           | include only topics added to given project               |
+| :project-status    | include only topics with any of given project status(es) |
+| :no-project-status | exclude topics with any of given project status(es)      |
 
 All properties are optional (but at least one should be provided). Multiple
 properties are ANDed, e.g. (:author "bob" :label "bug") matches topics with
@@ -509,6 +493,26 @@ Note that not all statuses are mutually exclusive, in particular =required= can
 co-exist with any status except =undecided=, and =commented= can co-exist with
 any other status. You can match multiple statuses by providing a list.
 
+=:project= property can have one of the two forms:
+ - number
+ - (type number)
+
+Here, number is project id (you can see it in url), and optional type is either =v2=
+or =classic=. (Classic projects are deprecated by GitHub but are still in use). If
+type is omitted, =v2= is assumed.
+
+=:project-status= can be a string or a list of strings. For =v2= projects, it matches
+“status“ field of the project item, which corresponds to column name if board view of
+the project. For =classic= projects, it matches “column“ property of the project card.
+
+If you use =:project-status=, you should alsp specify =:project=.
+
+Examples:
+#+BEGIN_EXAMPLE
+  :project 5 :project-status "In work"
+  :project (classic 2) :project-status ("Backlog" "On hold")
+#+END_EXAMPLE
+
 =GITHUB-QUERY= is a string using github search syntax:
 https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
 
@@ -542,40 +546,6 @@ The latter allows to exclude fields that makes queries slower, when they're
 not used. To change this, you can specify =:fields= parameter explicitly.
 #+END:
 
-#+BEGIN: om-dash--readme-symbol :symbol org-dblock-write:om-dash-github-project-cards
-*** om-dash-github-project-cards
-Builds org heading with a table of github =classic= project cards.
-
-Note: if you're using new github projects (a.k.a. projects v2, a.k.a projects beta),
-which are currently default, then use =om-dash-github-project-items= instead.
-
-Usage example:
-#+BEGIN_EXAMPLE
-  ,#+BEGIN: om-dash-github-project-cards :repo "owner/repo" :type issue :project 123 :column "name"
-  ...
-  ,#+END:
-#+END_EXAMPLE
-
-Parameters:
-
-| parameter      | default                  | description                            |
-|----------------+--------------------------+----------------------------------------|
-| :repo          | required                 | github repo in form “<owner>/<repo>“   |
-| :type          | required                 | topic type (=issue=, =pullreq=, =any=) |
-| :state         | =open=                   | topic state (=open=, =closed=, =any=)  |
-| :project       | required                 | project identifier (number)            |
-| :column        | required                 | project column name (string)           |
-| :table-columns | =om-dash-github-columns= | list of columns to display             |
-| :headline      | auto                     | text for generated org heading         |
-| :heading-level | auto                     | level for generated org heading        |
-
-=:type= defines that types of cards to display: issues, pull requests, or all.
-=:state= defines whether to display open and closed issues and pull requests.
-
-=:project= field specifies project numeric identifier (you can see it in URL on github).
-=:column= field specifies string name of a project column.
-#+END:
-
 #+BEGIN: om-dash--readme-symbol :symbol org-dblock-write:om-dash-orgfile
 *** om-dash-orgfile
 Builds org headings with tables based on another org file.
@@ -761,14 +731,14 @@ Builds org heading with a table from output of a elisp function.
 
 Usage example:
 #+BEGIN_EXAMPLE
-  ,#+BEGIN: om-dash-function :fun example-func
+  ,#+BEGIN: om-dash-function :func example-func
   ...
   ,#+END:
 #+END_EXAMPLE
 
 | parameter      | default  | description                     |
 |----------------+----------+---------------------------------|
-| :function      | required | elisp function to call          |
+| :func          | required | elisp function to call          |
 | :args          | nil      | optional function arguments     |
 | :headline      | auto     | text for generated org heading  |
 | :heading-level | auto     | level for generated org heading |
@@ -809,13 +779,13 @@ This section lists built-in templates provided by =om-dash=. You can define your
 #+BEGIN: om-dash--readme-symbol :symbol om-dash-github:milestone
 *** om-dash-github:milestone
 This template is OBSOLETE.
-Use =om-dash-github-topics= with =:milestone= query instead.
+Use =om-dash-github= with =:milestone= query instead.
 #+END:
 
 #+BEGIN: om-dash--readme-symbol :symbol om-dash-github:project-column
 *** om-dash-github:project-column
 This template is OBSOLETE.
-Use =om-dash-github-project-items= or =om-dash-github-project-cards= dynamic blocks instead.
+Use =om-dash-github= with =:project-status= query instead.
 #+END:
 
 ** Minor mode
@@ -844,14 +814,14 @@ org tables generated by om-dash dynamic blocks.
 Things that are highlighted:
  - table header and cell (text and background)
  - org-mode keywords
- - issue or pull request state, number, author
+ - issue or pull request state, number, author, etc.
  - tags
 
 After editing keywords list, you need to reactivate minor mode for
 changes to take effect.
 
-To active this mode automatically for specific files, you can use
-local variables (add this to the end of the file):
+To activate this mode automatically for specific files, you can use
+local variables, e.g. add this to the end of the file:
 
 #+BEGIN_EXAMPLE
   # Local Variables:
@@ -920,7 +890,7 @@ This function is invoked with dynamic block parameters plist and should
 return a new plist. The new plist is used to update the original
 parameters by appending new values and overwriting existing values.
 
-For example, if =org-dblock-write:om-dash-github-topics= block has parameters:
+For example, if =org-dblock-write:om-dash-github= block has parameters:
 #+BEGIN_EXAMPLE
   (:repo "owner/repo"
    :type 'issue
@@ -976,29 +946,31 @@ E.g. used for :created-at, :updated-at, :closed-at github columns.
 
 #+BEGIN: om-dash--readme-symbol :symbol om-dash-github-columns
 *** om-dash-github-columns
-Column list for =om-dash-github-topics= table.
+Column list for =om-dash-github= tables.
 
 Supported values:
 
-| symbol      | example           |
-|-------------+-------------------|
-| :state      | OPEN, CLOSED, ... |
-| :number     | #123              |
-| :milestone  | 1.2.3             |
-| :tags       | :tag1:tag2:...:   |
-| :author     | @octocat          |
-| :assignee   | @octocat,@github  |
-| :reviewer   | @octocat,@github  |
-| :title      | text              |
-| :title-link | [[link][text]]    |
-| :created-at | date              |
-| :updated-at | date              |
-| :closed-at  | date              |
+| symbol          | example           |
+|-----------------+-------------------|
+| :state          | OPEN, CLOSED, ... |
+| :number         | #123              |
+| :title          | text              |
+| :title-link     | [[link][text]]    |
+| :milestone      | 1.2.3             |
+| :tags           | :tag1:tag2:...:   |
+| :author         | @octocat          |
+| :assignee       | @octocat,@github  |
+| :reviewer       | @octocat,@github  |
+| :project        | text              |
+| :project-status | text              |
+| :created-at     | date              |
+| :updated-at     | date              |
+| :closed-at      | date              |
 #+END:
 
 #+BEGIN: om-dash--readme-symbol :symbol om-dash-orgfile-columns
 *** om-dash-orgfile-columns
-Column list for =om-dash-orgfile= table.
+Column list for =om-dash-orgfile= tables.
 
 Supported values:
 
@@ -1012,7 +984,7 @@ Supported values:
 
 #+BEGIN: om-dash--readme-symbol :symbol om-dash-imap-columns
 *** om-dash-imap-columns
-Column list for =om-dash-imap= table.
+Column list for =om-dash-imap= tables.
 
 Supported values:
 
@@ -1046,7 +1018,7 @@ slow down response times.
 There is also =om-dash-github-auto-enabled-fields=, which defines fields
 that are enabled automatically for a query if jq selector contains them.
 
-In addition, =org-dblock-write:om-dash-github-*= accept =:fields=
+In addition, =org-dblock-write:om-dash-github= accept =:fields=
 parameter, which can be used to overwrite fields list per-block.
 #+END: