Documentation | Create a process on when to create an issue vs MR vs both. (#20)

[Amar Takhar (@amar)]

Amar Takhar created an issue: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/20



## Summary

We don't have any formal documentation about when an issue should be created.  My proposal is to follow these two simple rules:

* If you need design and discussion before opening an MR create an issue.
* If you wish to collect multiple MRs for tracking create an issue or even better an [epic](https://docs.gitlab.com/ee/user/group/epics/).

Issues / tickets were important in the past because it allowed for tracking details related to a change.

MRs allow for inline commenting on patches and are threaded which makes for better engineering conversation especially with the code and iterative changes being possible.

What we do lose by not having issues:

* It's harder to track a change in git back to the MR because `git log` does not show the reverse connection.\\
  * This is not a great solution as we've already lost track of some of these numbers see below.

A solution to the above problem is to annotate commits using `git note`.  These do not change commit hashes and are stored out of band.  It also does not come up unless you explicitly look for the note so we can add whatever information we like here.  If we ever migrate off of GitLab we can change these notes to point to whatever new platform we choose.

We already have the problem where issue numbers are different and over time if we are unable to keep the numbers the same these will lose meaning.  Git notes are freely modifiable and do not suffer from this problem.

@chris @gedare @opticron @joel

-- 
View it on GitLab: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/20
You're receiving this email because of your account on gitlab.rtems.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/bugs/attachments/20240720/a6ca5fda/attachment.htm>