We can now use gitlab issues, how are we going to use them?

[Emmet O'Neill]

I've been using gitlab for some of my side projects, obviously on a much
smaller scale than Krita, but I hope it'll be a good fit for us once we all
get used to it.

Boards, Issues, Tasks, Milestones and Labels
>

It took me a little while to get used to the workflow here, but here's how
I tend to think about this:

   - *Boards* are best for representing a *pipeline *of *issues* and *tasks*.
   Kanban boards were created to support manufacturing pipelines, and so
   ideally tasks should "flow through" the board from stage to stage until
   completion. (For example, we might have a stage for "idea", another for
   "design", another for "implementation", and another for "polish". Issues
   and tasks flow through this pipeline from left to right, beginning as a
   mere idea, to becoming something polished and eventually completed.)
   - *Issues* represent *bigger ideas*, such as problems that need to be
   solved, large scale changes that need to be made, or anything that might
   need to be broken into individual *tasks*. Ideally issues will be things
   with a concrete solution or conclusion, so that we don't clog the pipeline
   with evergreen issues that will never be solved.  ("Update Krita for Qt6"
   is a good issue, because we can set a concrete goal. "Optimize Krita" is a
   bad issue because it's an ongoing, general thing that'll never be solved.)
   - *Tasks* represent smaller, more concrete and actionable ideas, which
   are the individual things that we need to do to solve an *issue*. Tasks
   should be clear, concise, and concrete steps. We define the issue first,
   then we break it into tasks, delegating those tasks if needed. There
   shouldn't be any ambiguity about what needs to be done to finish a task. We
   can think of tasks as a glorified checklist. (In fact, I believe you can
   convert checklist items within an issue into a task, which is a good way to
   go about it, imo.)
   - *Milestones* are entire projects, planned versions or points in time.
   (Like "Krita5.3", "Krita6", "GSoC2025", "CompanySponsoredProject2026",
   "AndroidStableRelease", your "TextToolProject" example, etc.)
   - *Labels* are basically just tags, like we're already using, but also
   applied to issues and tasks. Each column in a board is tied to a label, so
   it's important to have labels for each step in the dev pipeline too.
   ("Idea", "Design", "Implementation", "Polish", "Performance", "Feature",
   "Enhancement", "Bug", "Refactor", "CI", "UX", "Meta", "Marketing", are some
   ideas off the top of my head.)

Of course, that's just my interpretation and experience. We obviously can't
expect to nail all of this stuff right away or get anything perfect.

I update this
> flowchart manually, because for me issues are about *communication*.
> If I wanted to keep track of my tasks, I'd just use a paper notebook.
>

I agree with this, but another part of creating tasks is delegation, which
is something that's pretty hard in FOSS projects where we're all working
asynchronously, so to speak.
Ideally breaking projects into issues, and issues into tasks, will help us
share work and work together on things.

Issue boards however require use of labels, as that's how their
> columns are filled. They're automatic, and gitlab free can only use a
> single label to drive a single column.


One nuance here is that we don't *have to* have a board column for each
label.
In other words, *every column needs a label, but not every label needs a
column*.

Personally, I'd argue it would probably be a bad idea to create a column
for every label anyway, because it would make the pipeline less clear.
My recommendation would be to create as many labels as we think make sense,
but to try to minimize the number of board columns we start with.
(It's easier to start simple and add layers of complexity over time than it
is to start complex and simplify later, you know?)

We already use
> milestones for Krita releases, will we continue this way?


I think this is certainly a good way to go.

Milestones for "events" and "projects", including Krita releases, large
projects, etc.
Boards for "pipelines" where things go from stage to stage.
Issues for concrete problems or smaller projects.
Tasks for individual concrete...well, tasks.
Labels for categorizing everything as much as we want (though again, *start
simple and add over time*!)

You are responsible for the issues you create (that is, any issue
> that you create, you're the default assignee). Do not create issues
> for other people without their consent.


Ok

Do not create a ton of issues without consulting during a meeting or
> the mailinglist at kimageshop at kde.org. This is because big projects
> need to be discussed first.
>

I agree when it comes to issues.

With the exception of creating a *reasonable number of tasks* for your
issues as needed.
Let's just try not to spam or flood the boards with a million things.
Start with a checklist inside and issue and upgrade them to tasks as needed.

We should try to really value that clarity and organization of the board.

Breaking problems into a few manageable chunks is good organization.
Breaking problems into a thousand unmanageable grains of sand is bad
organization.

In a perfect world, we can all look at the board and have a decent sense of
what's going on, which means finding the right balance between big ideas
and smaller ones.

We probably should avoid having non-code issues in the
> graphics/krita repository. We have a repo for the funding website, one
> for documentation, and one for the regular website, and any of those
> would be fine. My problem with having them in the coding website is
> that we need to use that one the most, and non-coding issues tend to
> never close because of their ephemeral nature.


Fair enough.

How will we handle really big projects, like platform support
> (wayland/macos/windows/android), or the tablet ui?


Platform support is an ongoing thing, so it's kind of abstract. Same with
tablet UI.
Like you said above, we want to make sure that things are concrete and not
too ephemeral.
Other than Labels, everything that we add should have a "finish line", or
it'll just be there forever.

For example:

   - "Android" would be a *bad milestone*, issue or task (because what does
   it mean for "Android" to be done?)
   - "Android" would be a *good label* (so that we could tag issues and
   tasks as being relevant to android.)
   - "Android" would be a *bad board column* (because it doesn't represent
   a stage in the development pipeline that issues or tasks move through).
   - "AndroidStableRelease" or "AndroidStable-v1", however, would be a good
   milestone because we could consider that to be the first officially stable
   version for Android (and something we could use to organize a number of
   issues and tasks).

What about smaller projects like the panel cutter?


Ideally I think most projects should be issues, so that we can associate
them with a specific milestone.

So, in my opinion, we make "Panel Cutter Tool" an issue, we populate it
with a checklist of pseudo-tasks (which we can convert to proper tasks as
needed for elaboration or delegation), and we associate it with a milestone
like "Krita5.3".

With that said, I don't necessarily have a problem with occasionally
creating a milestone for big projects like you've done for the text tool.
The only downside to that (that I can see) is that we can't associate it
with a specific release milestone, afaik.

What about things like 'good first-time issues', 'xsimd porting' or
> even bugfixes?


"JuniorJob" and "Bug" should be labels.
"XSIMD Porting" should probably be an issue, with a "Performance" label,
and a associated release milestone.

What would you like to know about other projects? Issues are largely
> about communication, so what kind of things would make you feel like
> you understand other projects?


I'd like to know what a project is, who is working on it, how far along it
is, what it pertains to, and when it's planned to be finished.

What would you find annoying? Can we have some kind of workaround for that?
>

The only thing I would find annoying is adding too much, too soon.

There's a fine line between design and over-designing (and I'm just as
guilty of this as anyone else here!)
So, I'd like it if we could start with something simple, and add complexity
over time as needed.

I realize that's really subjective and somewhat vague, but basically if we
add things as needed I think it'll be better than getting too ahead of
ourselves and trying to preemptively add too many things to the point where
it becomes overwhelming for all of us.

- Emmet




On Mon, Jul 21, 2025 at 4:54 PM Wolthera <griffinvalley at gmail.com> wrote:

> Hi everyone,
>
> Ben enabled gitlab issues for us in the Krita repository. Reminder
> that we *shouldn't* copy any phab tasks, as Sysadmin wants to do the
> migration themselves.
>
> That said, I would have liked to take this time to spend some time
> discussing how we're going to use the new system as it's a little
> different from phab, and even then, some of us have never really used
> phab like we used to do. Unfortunately, someone already created issues
> before I even knew the issues were enabled. I none the less hope
> you'll entertain me, I think it'll be helpful if we pin it down now.
>
> ---
>
> I'd already been using issues for the text tool in my personal Krita
> fork. It's a little less powerful than phab, because a lot of features
> are behind the premium paywal. Still, let's review what we *can* do:
>
> Issues cannot be children of other issues. However, tasks (basically
> the same, but no mockups can be attached) can be children of issues,
> and furthermore, either can hold todo checklists.
>
> See this issue for an example of tasks as children of a main issue:
> https://invent.kde.org/woltherav/krita/-/issues/59
>
> Issues themselves can be organized under labels, milestones or
> issueboards. Furthermore, they *can* be arbitrarily linked to one
> another. That means we have a 4 level hierarchy available
> (Milestones/Issue boards > issues > tasks > todo lists). I think this
> will be sufficient, and the limitations will allow us to avoid
> hyper-analysis.
>
> The difference between milestones and issue boards is that the former
> is more controlled and the latter open-ended.
>
> Here's an example of a milestone (for the text tool):
>
> https://invent.kde.org/woltherav/krita/-/milestones/1#tab-issues
>
> And here's the text tool issue board:
>
> https://invent.kde.org/woltherav/krita/-/boards/9684
>
> As you can see, the text tool milestone has an introduction, with a
> flowchart. The flowchart is possible because gitlab can use
> mermaid.js. For another example, check the fonts issue
> (https://invent.kde.org/woltherav/krita/-/issues/52). I update this
> flowchart manually, because for me issues are about *communication*.
> If I wanted to keep track of my tasks, I'd just use a paper notebook.
>
> One thing I'd like to point out with milestones is their ability to
> allow you to filter which items in a particular label are open and
> closed inside the labels section of the milestone.
>
> Issue boards however require use of labels, as that's how their
> columns are filled. They're automatic, and gitlab free can only use a
> single label to drive a single column.
>
> So we'll need to decide how we're going to use this. We already use
> milestones for Krita releases, will we continue this way?
> ---
>
> We will, aside from deciding on how to use the tools available, also
> need to decide on some etiquette. I propose the following:
>
> - You are responsible for the issues you create (that is, any issue
> that you create, you're the default assignee). Do not create issues
> for other people without their consent.
> - Do not create a ton of issues without consulting during a meeting or
> the mailinglist at kimageshop at kde.org. This is because big projects
> need to be discussed first.
>   - The exception to this is issues for platform-related nonsense.
> When Apple or Microsoft or Google or whatever decide on some very
> novel/annoying new platform thing, or we need to keep track of a known
> vulnerability, and something *must* change before the next release.
> - We probably should avoid having non-code issues in the
> graphics/krita repository. We have a repo for the funding website, one
> for documentation, and one for the regular website, and any of those
> would be fine. My problem with having them in the coding website is
> that we need to use that one the most, and non-coding issues tend to
> never close because of their ephemeral nature.
>
> ---
>
> I'd like to invite you now to take a look at your own projects, and
> think about how you would use the issue system.
>
> - How will we handle really big projects, like platform support
> (wayland/macos/windows/android), or the tablet ui?
> - What about smaller projects like the panel cutter?
> - What about things like 'good first-time issues', 'xsimd porting' or
> even bugfixes?
> - What would you like to know about other projects? Issues are largely
> about communication, so what kind of things would make you feel like
> you understand other projects?
> - What would you find annoying? Can we have some kind of workaround for
> that?
>
> --
> Wolthera
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kimageshop/attachments/20250721/cc057882/attachment-0001.htm>