From 75213e26a04d3723ffb9b4ba1af7e4bd495bf76c Mon Sep 17 00:00:00 2001 From: Gregory Bartholomew Date: Dec 21 2021 16:34:24 +0000 Subject: Add Zinebot Operations page --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index c59e2d2..d5897f7 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -20,3 +20,4 @@ ** xref:technical-theme.adoc[Maintaining the Theme] ** xref:technical-pagure.adoc[Pagure Operations] ** xref:technical-wordpress.adoc[WordPress Operations] +** xref:technical-zinebot.adoc[Zinebot Operations] diff --git a/modules/ROOT/pages/technical-zinebot.adoc b/modules/ROOT/pages/technical-zinebot.adoc new file mode 100644 index 0000000..2e2e45e --- /dev/null +++ b/modules/ROOT/pages/technical-zinebot.adoc @@ -0,0 +1,206 @@ += Zinebot Operations + +Zinebot is a chatbot designed to help the xref:editor-of-the-week.adoc[editor of the week] run the xref:editorial-meetings.adoc[weekly meetings]. +Importantly, Zinebot is just an aid. +It is not required to run the meetings. +Its main purpose is to fetch information from various sources +to save the meeting chair from having to jump between several browser tabs or applications +and copy-paste information to or from the meeting chatroom. +The meetings can still be run in the traditional way if Zinebot crashes or otherwise fails to function. + +== Installation + +See https://pagure.io/fedora-magazine-chatbot[the Fedora Magazine chatbot repo] for installation instructions. +A good way to test Zinebot outside of meeting times +is to create a private room on https://chat.fedoraproject.org[the Fedora Project Matrix homeserver] +and invite the _zinebot_ user to the room. +You will need to assign the room a https://github.com/vector-im/element-web/issues/13077[local address]. +You can then configure Zinebot to join that room. + +== Commands + +:tilde: ~ + +Most of the Zinebot commands operate against https://pagure.io/fedora-magazine-newsroom/boards/articles[the Fedora Magazine kanban board]. +Notable exceptions include the `show`, `post` and `eotw` commands. + +All of the Zinebot commands must be prefixed with Zinebot's call sign and a space character. +Zinebot's call sign is the unicode diamond operator (⋄). +A convenient way to enter the diamond operator +is by using the https://help.gnome.org/misc/release-notes/40.0/#:~:text=Improved%20Settings[compose key]. +For example, if the compose key is enabled and configured to be the right-alt key, +then tapping the **Alt**, **<** and **>** keys in sequence should yield the diamond operator. +If so desired, Zinebot's call sign can be changed by editing its `run` script. + +TIP: Add the line: + + + +` : "🔹" U1F539 # SMALL BLUE DIAMOND` + + + +to your {tilde}/.XCompose file to remap the normal diamond operator compose sequence +to generate a small blue diamond instead. +You will need to restart your X11 or Wayland session for the change to take effect. +Zinebot will accept the small blue diamond character (🔹) as an alternative call sign. +You can still enter the normal diamond operator by tapping **Alt**, **>**, **<**. + +TIP: The full list of predefined compose keys can be found in the +/usr/share/X11/locale/en_US.UTF-8/Compose system file. + +TIP: You can customize the single character codes that Zinebot will respond to +by editing the {tilde}/.local/opt/zinebot/commands/hotkeys.pm file. + +=== 🔹 next topic + +Included with Zinebot is a `topics.txt` file containing a copy of xref:editorial-meetings.adoc[the meeting script]. +The `next topic` command will iteratively read the blocks of text listed in the `topics.txt` file and write them out in the chatroom. +The text blocks in the file are separated by blank lines. + +Some topics correlate with specific columns on the kanban board. +When appropriate, Zinebot will scan the cards from the corresponding kanban board column +and write them out to the chatroom as a summarized list. +Included in the summary for each card will be +an indication of whether or not the author has signed the Fedora Project Contributor Agreement (FPCA). +The status of the author's FPCA signature is retrieved directly +from the Fedora Account System each time a card is retrieved from the kanban board. + +=== 🔹 next col[umn] + +Internally, Zinebot keeps track of which kanban column is currently being viewed. +This command advances to the next column on the kanban board and lists its cards. +Normally, this command should not be needed since the `next topic` command will take care of advancing to the appropriate column. + +=== 🔹 next card + +Internally, Zinebot keeps track of which card on the current kanban column is being viewed. +This command advances to the next card in the column and displays its summary. +If you want to view a specific card rather than iterating through them in order, +see the `view` command below. + +As a shorthand for this command, Zinebot will accept a lone unicode _right-pointing arrow_ (→). +The call sign should be omitted when using the shorthand. + +=== 🔹 skip topic + +This command allows you to skip to a specific topic. +For example, `skip topic agenda` or `skip topic 7`. +This command will reset the internal topic counter such that the result of a subsequent `next topic` command will be changed. +Otherwise, this command behaves exactly like the `next topic` command. + +=== 🔹 show proposed + +When the _to-edit_ column is loaded in the current internal card deck, +this command will read the scheduled publication dates from all the cards in the deck and list them out +along with the card titles and assigned editors as a proposed editing and publication schedule. + +As a shorthand for this command, Zinebot will accept a lone unicode _because_ symbol (∵). +The call sign should be omitted when using the shorthand. + +NOTE: The default compose key sequence for the _because_ symbol is ****, **.**, **:**. + +=== 🔹 show agreed + +This command generates the same output as the `proposed` command described above. +However, instead of starting with _#proposed_, the output will begin with _#agreed_. + +In the background, this command will also post the agreed-upon publication schedule to Fedora Magazine's channel +on https://discussion.fedoraproject.org[the Fedora Project Discourse forum]. +The success or failure of each attempted post is indicated +by a respective 🔹 or 🔸 at the end of each scheduled card. +Only articles that are scheduled for the upcoming week should post successfully. +Anything that is scheduled for an earlier or later date should automatically fail to post. + +As a shorthand for this command, Zinebot will accept a lone unicode _therefore_ symbol (∴). +The call sign should be omitted when using the shorthand. + +NOTE: The default compose key sequence for the _therefore_ symbol is ****, **:**, **.**. + +=== 🔹 show testdays + +This command scans https://calendar.fedoraproject.org/QA[the Fedora Project QA calendar] for test day events +and displays them in the chatroom. +The scan is limited to a three-week period that begins on Sunday of the current week. +Test day events are identified as those whose _meeting location_ is set to _fedora-test-day*_. + +=== 🔹 show schedule + +This command scans https://fedorapeople.org/groups/schedule[the Fedora Project schedule] for scheduled Fedora Magazine publications +such as beta and final release announcements. +The results are then listed in the chatroom. + +=== 🔹 list [column] + +This command generates a summarized list of kanban cards from either +the current kanban column or, if specified, the requested kanban column. +The `next topic`, `skip topic` and `next column` commands call this command automatically. +When a specific column is requested, all subsequent Zinebot commands will consider it the _current_ column. + +Internally, the `next card` and `view` Zinebot commands operate against a cache of cards retrieved from the current kanban column +rather than fetching them from Pagure each time. +This command repopulates the internal cache whenever it is called. +The current card is also reset to the first card in the list. +If you modify any of the cards that are cached, you may need to rerun this command to update the internal cache. + +=== 🔹 view [number] + +This command does exactly the same thing as the `next card` command. +However, unlike the later, it allows you to specify a specific card number to display. +The requested card must be loaded in the current card cache from a prior run of the `list` command. +When a specific card is requested, the current card index for the next run of the `next card` command is not advanced. + +=== 🔹 card [ ...] + +This is a low-level command that allows you to access individual card properties. +When provided a card number, this command operates directly against Pagure. +This command can access cards that are not in the current column. +The following card properties are accessible through this command. + +[listing,indent=1] +🞄 id +🞄 title +🞄 full_url +🞄 content +🞄 comments[:N] +🞄 + +By default, the last three comments are retrieved from the card when the `comments` property is requested. +The number of comments to retrieve can be specified by appending **:N** to the property name where **N** is a positive integer. +All card comments can be requested by appending **:0** to the property name. + +=== 🔹 move [row] + +This command moves the specified card to the specified kanban column. +Optionally, the row offset at which the card should be placed in the target column can be specified. +By default, cards are moved to the top of the target column (row 1). + +As a shorthand, you can use the unicode characters ← or → in place of the column name +to signify the previous or next column respectively. + +NOTE: The default compose key sequence for the _leftwards arrow_ symbol is ****, **<**, **-**. + +NOTE: The default compose key sequence for the _rightwards arrow_ symbol is ****, **-**, **>**. + +=== 🔹 ping + +This command adds a one-line comment to the specified card. +Pagure should send an email notification to the card's assignee containing the comment. +The comment does not need to be quoted. +Everything after the card number is considered part of the comment. + +=== 🔹 post [date [time]] + +This command posts an event to the Fedora Magazine calendar on Fedora's Discourse forum. +If the date is not specified, it defaults to one week from the current day. +If the time is not specified, it defaults to the beginning of the current hour. +Dates must be specified as YYYY-MM-DD. +Times must be specified as HH:MM:SS. +Times are in Coordinated Universal Time (UTC). +The title does not need to be quoted. +Anything that does not match a date or time pattern is considered part of the event title. + +This command is called automatically by the `show agreed` command +to add the agreed-upon articles to the publication calendar. + +=== 🔹 eotw <username> + +This command posts the editor of the week line. +Just for fun, `king` and `queen` are aliases for this command. They may be easier to remember. +