IGWN Computing Project Management Guidelines¶

The IGWN Computing and Software Working Group use GitLab (hosted at https://git.ligo.org) for Project Management.

This guideline is a work in progress; suggestions for edits should be made freely to the via issues.

Executive summary¶

The following guidelines are critical to effective use of GitLab for Project Management.

All 'official' IGWN Computing activities should be hosted under the top-level https://git.ligo.org/Computing group.

Exceptions:
- projects that require regular input from non-IGWN members. At this time we are unable to provision GitLab accounts for external collaborators.
- projects that need to be kept confidential from the IGWN Computing Group at large.
All work items should be represented in GitLab either as an Epic or an Issue.

The only standard exceptions to this are ongoing Maintenance and Operations or Support tasks related to persistent services and tools, although this may change in the future.

Group and Project structure¶

Having an activity represented in GitLab is crucial to the integration of that activity into the overall IGWN Computing work plan.

Ideally, all activities would be nested in a subgroup related to the relevant Work Package, but that structure is currently in development.

Normally each IGWN Computing activity would be represented naturally as a GitLab Project, however, creating a Group to house related activities might be a better representation. For example, for the GWDataFind service, there exists a https://git.ligo.org/computing/gwdatafind group that houses individual projects for the server and client. This structure enables independent work on the server and client, but also combined planning of features via group-level planning. The structure then looks like this:

graph LR; A(["Computing #128101;"]):::GRP; A --> B(["GWDataFind #128101;"]):::GRP; B --> C1("Client #9881;"):::PRJ; B --> C2("Server #9881;"):::PRJ; classDef GRP fill:#516091;

There is no hard and fast rule for group/project organisation, please use your best judgement, or ask the IGWN Computing leadership for a recommendation.

Epics¶

Epics provide a way to organise sets of work items (issues) that share a common theme/goal.

Key features¶

Epics are group-level features
Epics can be nested with multiple child epics
Epics can be linked to other epics, with simple relationships (related to, blocks, blocked by)
Epics can be represented as a Gantt-style Roadmap
An issue can be associated with one (and only one) epic
Epics can be visualised on an epic board, more below

Known limitations¶

Epics cannot be assigned to one or more individuals/groups (epic)
Epics cannot be created in projects (issue)
Epics cannot be created at the instance level (issue)
~~Epics cannot contain issues from above their parent group (epic)~~

This is now resolved to the point where issues can be added to epics in arbitrary groups, but only from the epic page, and not from the issue page (comment).

Guidelines¶

Do not set the start and end date for epics¶

Epics can have their start and end date inherited from their child-epics and issues. It is recommended that you associate all issues to a milestone that has start and end dates, such that their epics will inherit these dates and populate the roadmap appropriately.

Issues¶

Issues are the key feature of GitLab that enables planning of work.

Key features¶

Issues are project-level features.
Issues can be made confidential to restrict their visibility to members of the parent project only. WARNING: in the (current) GitLab membership hierarchy, a project's membership includes all members of the parent group(s).
Issues can be linked to other issues to describe interdependencies.
Issues can be associated with one (and only one) epic
Issues can be associated with one (and only one) milestone

Guidelines¶

Every task should be an issue¶

Every non-trivial task related to IGWN Computing should be filed as an issue.

This will enable this task to be scheduled (via milestones) and integrated into the overall IGWN Computing work plan (via epics).

If an issue spawns sub-tasks, promote it to an epic¶

If an issue evolves to spawn multiple sub-tasks that can each be represented by an issue, promote the original issue to an epic and associate all of the sub-tasks issues to the new epic.

This allows detailed understanding of the steps necessary to complete a task.

Use issue templates¶

Issue templates should be used to simplify creation of repetetive types of issues (feedback, release requests, support requests, ...).

Direct links can be created to the 'New Issue' page with a specific template pre-selected by using the issuable_template URL query parameter, e.g.

https://git.ligo.org/computing/helpdesk/-/issues/new?issueable_template=Software

All error pages for services (e.g. 404, 500 HTTP errors) should provide these templated links encouraging visitors to open support tickets as appropriate.

Assign an epic and a milestone to all Issues¶

All issues should be assigned to an epic and and a milestone as early as possible, where appropriate.

Assigning to an epic will integrate the issue into the IGWN Computing work plan, and so should be applied at least to all issues representing development work (e.g. feature requests).

Assigning to a milestone will indicate the timeline for resolution of an issue, and will integrate that timeline into the roadmap for the epic hierarchy (if an epic is also assigned).

Milestones¶

Milestones are a way to track issues and merge requests over periods of time.

Key features¶

Milestones are both project- and group-level features
Milestones can have start and end dates
Issues and merge requests can be associated with one (and only one) milestone

Known limitations¶

Milestones cannot be created at the instance level, or shared across groups (issue)
Group milestones are not visible from the Project milestones list (issue)

Guidelines¶

Include a project prefix in the milestone name¶

Because project and group milestones are shown together on roadmaps and in group milestone lists, a consistent naming convention is required to distinguish milestones across groups and projects.

All milestone names should include a common prefix for that group or project. Ideally the prefix should be short, but enough to uniquely identify the context of the milestone.

for project milestones, include the (short) name of the project in the milestone, e.g. gwdatafind 1.2.3 (rather than 1.2.3)
for group milestones, include the (short/abbreviated) name of the group in the milestone

Create milestones at the lowest level needed¶

Since milestones can be defined both for groups and projects, it is best to define a milestone at the lowest (deepest) level possible

If the milestone only applies to a specific project, then create the milestone there.
If the milestone applies to a group of projects, then create the milestone at the lowest possible group.

This will assist in filtering milestones, e.g. when applying to issues, and prevent confusion over the scope of a milestone.

Labels¶

Labels are a way to categorise epics, issues, and merge requests according to enable filtering and grouping of tasks.

Key features¶

Labels are both a group- and project-level feature.
Project labels can be assigned to issues and merge requests in that project.
Group labels can be assigned to epics, issues, and merge requests in that group and any subgroups.
Labels can be scoped to create groups of mutually-exclusive labels.
Users can subscribe to receive notifications whenever a label is assigned to an epic, issue, or merge request.

Guidelines¶

Create labels at the lowest level needed¶

Since labels are visible to all subgroups and projects beneath them, many group-level labels would create a cluttered interface, and create confusion on which labels to apply.

Group-level labels should be restricted to concepts that are applicable at the group level.

If you are unsure on whether to create a group-level or project-level label, start with a project label; it can always be promoted to a group label in the future.

Create scoped labels to remove confusion¶

Scoped labels enable the creation of mutually-exclusive labels, typically representing stages along a sequence. Scoped labels should be used where possible to automate management of labels, rather than relying on users to remove invalid labels manually.

Add a description to all labels¶

All labels should be created with a description. This should be one or two sentences (no more) that describes the context of a label. This information will be presented in a (hover) tooltip above the label in the web interface.

Boards¶

Boards provide a way to visualise and manage lists of issues and epics based on their labels, assignee, milestone, or iteration.

Key features¶

Boards are both a group- and project-level feature.
Boards can be created to view issues or epics.
Items in a list can be reordered by dragging them around in the user interface.
Each list in a board can be scoped with one of the following
- a label
- an assignee (issue boards only)
- a milestone (issue boards only)
- an iteration (issue boards only)
Moving items from one list to another will then remove the label/assignee/milestone/iteration from the old list and add the label/assignee/milestone/iteration for the new list.
Boards can be filtered by author, assignee, type, label, etc

Known limitations¶

The ordering of issues/epics in a list can only be done by dragging issues around in the UI, and there is no history or record of the change, who made it, or why.

Guidelines¶

Define boards at the lowest level needed¶

Boards should be created at the lowest level needed (i.e. at the project-level rather than the (sub)group-level, if appropriate). If all relevant issues for a board are in one project, create a project board.

Define boards for each scoped label set¶

If you are using scoped labels, you should consider creating a board that visualises the scoped label set. See the SCCB's Procedure board for an example.