Skip to content

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 represented as a Gantt-style Roadmap
  • An issue can be associated with one (and only one) epic

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 (issue)

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

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.