0

I'm starting to define how issues should be handled in GitLab. Most specifically whether the author should be editing the original issue to keep it up to date or use only comments.

Let's say that you start working on a feature. The first thing you do is add a first analysis and design. Now one of the collaborators spots some flaws in the design, should the author then edit the issue to fix the design, or should he/she reflect the change in a comment?

The former keeps the original issue always up-to-date, so if in the future you need to take a look at the analysis done, there's no need to scroll over a bunch of comments to reach the conclusion. However, you lose the traceability of the comments, as one comment might reference something that has been removed.

Is there a preferred way of handling this?

EDIT: to clarify further, this is for internal purposes. There's no external parties or people involved.

Improve this question
2
  • 1
    Microsoft has moved all of the design for C#, Visual Basic.NET, .NET, and CLR into GitHub (and as sort of a pathfinder, before all of that, they already had it for TypeScript as well). You might want to check out how they are doing it. Commented Apr 16, 2021 at 19:03
  • In either case, I would suggesting have at least some portion of the issue desc dedicated to summarizing the latest conclusions in the thread. I've been burned in the past by learning things from browsing issues (only skimming their descriptions and not their 10s of comments), and later finding out that I was accidentally propagating false/out-dated information, false assumptions, etc. Commented Apr 17, 2021 at 23:20

2 Answers 2

Reset to default
4

Ultimately, it depends on your particular situation. However, there are some factors that can help to build a suitable process.

  • Are the issue authors part of your team, or external? Maintaining standards about how your issues are structured will be easier within your team. It will be difficult to impossible to enforce them to external collaborators. If a process relies on continuous effort from a person who is not committed to this process, it will fail.

  • Who are you writing for? Within an issue discussion, posting a separate comment might be better. This will also conveniently notify other participants in the discussion. If you're only reformatting stuff, or summarizing the discussion for future reference, an edit could be better.

  • Is an issue the best medium for this work? Issues allow back-and-forth and discussion and are good for solving problems, but aren't really about building an artefact that can be referenced later.

    In more process-oriented environments, it might be better to actually write a design document. Discussion about this document could then be handled in the pull request that adds the document to some repository. Comments can then be made about specific lines in the proposal, and the document updated accordingly. Later, it is sufficient to read the document – the issue/pull request only explains the history of how the document was created. As an example of such a process consider Rust RFCs, but note that a diverse open source project is a totally different environment from a tight-knit team (see also my first point).

    Another aspect of this is writing something together. E.g. one of the core advantages of Stack Exchange compared to other platforms is that I can directly edit other people's posts. For a design discussion, a more wiki-like experience could be suitable. In the end, it's important that agreement about a design is reached, not who was the author.

Improve this answer
1
  • Thanks for the reply! I've edited the question to specify that this is for a closed team. I also considered Rusts RFCs as a way of doing these kind of things and it's starting to look like a better starting point. Commented Apr 16, 2021 at 19:02
3

If issues are used as "work orders", a description of what needs to be done and how it should be done, then you should probably update them so the issue always reflects the final work order. Otherwise where would a developer find the final work order? Having to reconstruct it from the initial, now deprecated one and the fifty comments made below it that alter it in one way or another? In that case it is irrelevant if comments refer to old versions of the work order because a developer doesn't even have to read the old comments, only the final work order is relevant for them. Only if the developer has questions or own comments, replies to those would be relevant and should again be used to update the issue itself.

If issues are only "error reports", that mention the problem, yet provide no concrete solution, or maybe only a suggestion for one, and finding the final solution is done by discussion lead through comments, then you should never edit anything (except typos and grammar mistakes), to retain the history of how the final solution has developed. In a group chat you would also not go back up edit the content old messages based on the content of new ones, would you? Only by keeping all suggestions, objections and rejections it will be comprehensible why a particular solution was chosen in the end. Same thing applies to "feature requests", which are often very vague in the beginning.

The second approach is usually used where access is public and issues may also be created by end users, as these only report problems or send in wishes, yet they are not involved in the development itself and also cannot make decisions about the implementation or whether something is implemented at all. The first approach is rather used in closed groups, where the concrete future development and releases are planned.

We use both approaches. If someone discovers an issue or has a feature request (e.g. a developer, a tester, or a supporter on behalf of a customer), an issue is created which only explains the issue or wish. If it's pretty much clear what needs to be done to resolve the issue, it can be directly added to a planned release (milestone) and get assigned to a developer.

If not, it is used as the base for discussion to find an acceptable solution (or close it, if none can be found). In case such a solution is found, that solution is written to a new issue as a "work order", this "work order" is then added to a milestone and assigned to a developer. The two issues are bound together using the link feature (so each one references the other one on top) and when the new issues is closed, the initial is closed as well.

Depending on the type of issue, we use one or the other update strategy. As for marking the type, you can create dedicated issue types in Gitlab or just tag one of them with a special label.

Improve this answer
1
  • Thanks for the reply! The last three paragraphs, combined with Rust RFCs, as pointed out by @amon is what I think makes more sense for our case. Commented Apr 19, 2021 at 8:01

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.