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.

Issue Branch

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.

Create Issue

Use the command below to create an issue:

kit issue create

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.

Use an Editor

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.

Add Labels

The issue can include labels and assignees. Add up to 10 labels using --labels flag.

kit issue create --labels="bug,help-wanted"

Add Assignees

Add up to 10 push keys as assignees.

kit issue create --assignees="pk1e29gepyt8pzumrzjt9t508elgxpy62drezeect,pk1caskzq6leplwcj2su4jtsyu4w3fzutvl44hfn7"

Add a Comment

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 

The-iflag is not required if you are already checked into the issue.

Add a Reply

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"

Add a Reaction

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"

List All Issues

List all issues in the repository with list command:

kit issue list

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.

Read an Issue

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

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

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.

Re-open an 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”.

Check Issue Status

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 updated