Issue Management
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 specialissuesdirectory. 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:
kit issue create
Title> My issue titleBody> 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.
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.
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.
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:
kit issue list
issue daba0231b9cd6882c0305ee7dda4380b35399f88 issues/2Title: Fix the config loaderAuthor: John [email protected]Date: Wed Aug 5 22:41:05 2020 +0100The thing has refused to load quickly...issue 95a0d4a6de1af728dbb47a385ff59ed162b16166 issues/1Title: Noticing false warningsAuthor: Snow [email protected]Date: Sun Aug 2 16:25:46 2020 +0100ReplyTo: ab91ed58a04a5ee3d81c06bd481700f7b27c75ecReactions: ☺: 1, ❇️: 1Is 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:
kit issue read 2
comments daba0231b9cd6882c0305ee7dda4380b35399f88 #0Author: John <[email protected]>Title: Fix the config loaderDate: Wed Aug 5 22:41:05 2020 +0100The 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.
