Issue Management
Create, read, list, react and close issue.
In this section, you will learn how to:
- Create an issue.
- List issues.
- Read an issue.
- Close and Open an issue
Git is great. It was built to be very modular and as such does not come with many of the collaboration primitives we use today. One of which is a protocol for issue management.
Issue management is an essential part of developers day-to-day activity. Developers rely on issue management systems to track and discuss problems they find in their codebase or those of projects they care about.
It is also a major driver of platform lock-in on centralized code sharing platforms. On these platforms, there are no issue management standards or a federated protocol for managing issues. Collaborators cannot simply and freely download and move their data to another platform in a way that is easy and compatible with the destination platform.
MakeOS includes an issue management protocol built right into a repository using already existing git protocol. It is offline-first and anyone can build visualization and interactive tools on top of it.
An issue is represented by a branch under the special
issuesdirectory. An issue branch must contain only a file namedpostwhich contains a frontmatter section (for storing metadata) and a body section. Adding a comment to an issue branch is as simple as updating thepostfile and committing it.Use the command below to create an issue:
Bash
Output
kit issue create
Title> My issue title
Body> I was trying to initialize the adapter...
✅ New issue created!
refs/heads/issues/1#0
The command above will start an interactive session that will ask for a
title and body of the issue. On success, it will create an issue branch at
.git/heads/issues/1. Issues must have a numeric ID; The Kit client will create issues with a monotonically increasing number as the name. You can use
-i flag to specify a different numerical number or to add a comment to an existing issue. Writing a multi-line issue body on the terminal can be inconvenient. Use the
--use-editorflag to launch an editor. The default editor is sourced from git's config option
core.editor. You can provide an editor of your choice by changing the value ofcore.editoror using the--editorflag.The issue can include labels and assignees. Add up to 10 labels using
--labels flag.kit issue create --labels="bug,help-wanted"
Add up to 10 push keys as assignees.
kit issue create --assignees="pk1e29gepyt8pzumrzjt9t508elgxpy62drezeect,pk1caskzq6leplwcj2su4jtsyu4w3fzutvl44hfn7"
Every commit in an issue branch represents a comment or a response to another commit (or comment) in the same branch. You can add a comment by specifying the target issue ID using the
-i flag.Bash
Output
kit issue create -i=1
Body> We may need to re-think the init sequence...
✅ New comment added!
refs/heads/issues/1#50
The
-iflag is not required if you are already checked into the issue.Similar to comments, a reply is a commit that references the hash of another commit in the same branch. You can add a comment by providing the target commit hash using
--reply or -r flags.Bash
Output
kit issue create -i=1 --reply="0f67159cea65546...c861289160f"
Body> Something about the way it works...
✅ New comment added!
refs/heads/issues/1#2
A reaction adds an emoji to a comment being replied to. MakeOS supports the v13.0 emoji list which offers a large collection of emojis to enable collaborators to express themselves however they wish.
Add reactions to a reply by using the
--reactions or -e flags.Bash
Output
kit issue create -i=1 --reply="0f67159cea65546...c861289160f" -e="smiling_face,sparkle"
Body> I cannot wait to see how...
✅ New comment added!
refs/heads/issues/1#2
List all issues in the repository with
list command: Bash
Output
kit issue list
issue daba0231b9cd6882c0305ee7dda4380b35399f88 issues/2
Title: Fix the config loader
Author: John [email protected]
Date: Wed Aug 5 22:41:05 2020 +0100
The thing has refused to load quickly...
issue 95a0d4a6de1af728dbb47a385ff59ed162b16166 issues/1
Title: Noticing false warnings
Author: Snow [email protected]
Date: Sun Aug 2 16:25:46 2020 +0100
ReplyTo: ab91ed58a04a5ee3d81c06bd481700f7b27c75ec
Reactions: ☺: 1, ❇️: 1
Is it normal for the alert to fire on...
The command above will list all issues ordered by their commit date in descending order. Use the
--reverseflag to reverse the order. You can also limit the number of issues returned with --limit or -n flags. Use the
read command to read the comments of a specific issue. Supposing there is an issue with ID = 2, it can be read like this:Bash
Output
kit issue read 2
comments daba0231b9cd6882c0305ee7dda4380b35399f88 #0
Author: John <[email protected]>
Title: Fix the config loader
Date: Wed Aug 5 22:41:05 2020 +0100
The component has refused to load quickly...
Like the list command, it will list all comments ordered by their commit date in descending order. Use
--reverse to reverse the order. You can also limit the number of comments returned with --limit or -n flags.Close an issue with the
closecommand. Supposing we want to close an issue with ID = 2, we can do it with the command below:kit issue close 2
Once an issue has been closed and pushed to remote, new comments will not be accepted unless the comment include a directive to re-opened the issue.
To reopen a closed issue, use the
reopen command. The command below will reopen an issue with an ID of 2.kit issue reopen 2
It creates a new comment that includes a directive in the front-matter section instructing the network to update the issue's state to “open”.
If you want to know the status of an issue, you can use
status command.kit issue status 2
The command prints either
opened or closed.Last modified 2yr ago