edhil import

edhil import [FILE] [--epic NUMBER] [--dry-run [--json]] [--yes]

Creates the issues of a markdown document in the forge: an epic and its work items, or only work items added to an epic that exists. The document is the output of the refinement of an epic (see Working with edhil): a description of the epic and one block for each work item.

The document

The document is split on lines that are three or more hyphens and nothing else (---, -----), except inside a fenced code block. The first block is the epic: its first heading is the title of the epic. Every other block that has a work item heading is a work item. Only ASCII is accepted, apart from the accented letters of Latin-1 (U+00C0 to U+00FF, without the multiplication and division signs).

# Epic 5 - Journal storage

**Project:** #161
**Milestone:** M2 - Storage

The text of the epic, as long as you like. It becomes the description of the epic.

---

## WI #5.1 - Create the tables

### High level summary

What the work item does and why.

### Steps

The files to change and the code to write.

### Definition of done

1. The tables exist.

### Verification steps

```verify
yet cleanify
cargo test -p edhil
```

---

## WI #5.2 - Write the first entry

### High level summary

Depends on WI #5.1. The reference is rewritten to the real issue number.

### Steps

...

### Definition of done

1. ...

### Verification steps

```verify
yet prepush
```

The rules, all of them (the same rules, with the error codes, are in The epic document format):

  • The epic heading is # Epic N - Title. The Epic N - part is removed, so the epic is called Title. A **Project:** #N line (or Project: N) right after the heading is mandatory: N is the number of the project issue that the epic belongs to (see “The project” below).
  • A work item heading is ## WI #N.M - Title (also ## WI N.M - Title or ## Issue #N.M - Title). N.M is the identifier of the work item in the document. It is only used to link the work items to each other and to show them in the preview.
  • The identifier and the title are separated by a run of hyphens of any length: -, -- and --- all work, and hyphens inside the title are kept. Only the ASCII hyphen separates; an em dash does not.
  • A work item has exactly four sections, in this order: ### High level summary, ### Steps, ### Definition of done and ### Verification steps. The Verification steps section has exactly one fenced block labelled verify, with one command per line. The commands are split into words without a shell: pipes, &&, redirections and $ are errors.
  • Everything else in a block is kept as the description.
  • References to other work items of the document (WI #5.1 or #5.1) are rewritten to the real issue numbers of the created issues. References to identifiers that are not in the document are left alone.
  • A block without a work item heading, other than the first, is ignored.
  • With --epic, the document must not have an epic block.

What is created

For a new epic: the labels Epics, Work Items and the label of the project, when they do not exist; one issue with the labels Epics and the project label, with a relates_to link to the project issue; and one issue for each work item with the labels Work Items and the project label, the line Parent Epic: #N at the end of its description, and a relates_to link to the epic. No label is named after the epic. The work items are created in the order of the document. The epic is never closed by edhil.

With --epic NUMBER: only the work items are created, in epic NUMBER, with the labels Work Items and the project label of the epic. The epic is checked in the forge before anything is created: it must exist, be an epic and be open. The document has no epic block in this mode: an epic heading is an error. This is how review findings are added to an epic that is already imported.

The project

A project is an issue with the Projects label that you write by hand in the forge. Its title is the label that the epic and its work items get, so the work of one project can be found by that label.

  • A new epic names its project in the Project line. The project issue must exist, be open and have the Projects label. Its title must be usable as a label: not empty, without a comma, and none of Epics, Work Items and Projects. If a check fails, nothing is created.
  • An existing epic gets its project from its links: the epic must be linked to exactly one issue with the Projects label. If it is linked to none, link it with /relate #<project number> in a comment on the epic. If it is linked to several, remove the links that do not belong.

The preview and the question

Before anything is created the command shows what it is going to do and asks Create N issues? [Y/n].

New epic: Commit
Project: #161
7 work items:
  11.1  Issues: None in the message format  (2 verification commands)
  11.2  The editor, the template and reading the message back  (1 verification command)
  ...
8 issues would be created.

After the checks in the forge, and before the question, the command also shows the label of the project and the labels that it is going to create:

Project label: Work Item Specification
Labels to create: Epics, Work Items, Work Item Specification

With --epic it shows Project: #N first, the number of the project found through the links of the epic.

An empty answer or y creates the issues. Anything else prints Cancelled; nothing was created. and exits with 1. When the issues are created it prints their numbers and links:

Created the epic #14  https://gitlab.com/mygroup/myproject/-/issues/14
  #15  11.1  Issues: None in the message format  https://gitlab.com/mygroup/myproject/-/issues/15

Options

Option Meaning
FILE The markdown file. Without it, or with -, the document is read from standard input. With no file and a terminal as standard input the command does not wait for typing: it is a usage error (exit code 2).
--epic NUMBER Add the work items to this existing epic instead of creating one.
--dry-run Show the preview and stop. It needs no configuration and no token, and it does not check the project in the forge.
--json With --dry-run: print the parsed document as JSON (the epic, and for each work item its sections and verification commands, or the list of errors) instead of the preview. Exit code 0 if the document is valid, 1 if not.
--yes Create without asking. Required when the document comes from standard input, because the question could not be answered there, and when there is no terminal.
edhil import epic-5.md --dry-run
cat epic-5.md | edhil import --yes
edhil import findings.md --epic 5

Good to know

  • Nothing is created if the document cannot be parsed or if the project cannot be used. Every error is listed with its line: for example a missing section, a missing Project line, a character that is not allowed, or a command that needs a shell.
  • If the forge fails or refuses a request halfway, the command prints Importing failed: <reason> and a list of what was created before the failure: the epic and the work items, with their links. On a terminal it asks (r)etry or (a)bort?. Retry goes on where the failure stopped, so nothing is created twice. Abort ends the command with Aborted after a failure and the same list. Without a terminal, or without an answer, the import ends the same way. Do not import the whole document again after a failure, or the issues in the list are created twice. Check with edhil work-items, then finish by hand in the forge, or remove the work items in the list from the document and import the rest with --epic.
  • The checks of the format that --dry-run makes are also made by tools/edhil-validate/edhil_validate.py, which needs only Python and can run in CI. The heading of a work item stays at the top of its description in the forge, because edhil implement reads the commands back from it.
  • The links are built from the url and the project or repository of the configuration; What differs between the forges shows their form.