<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en" style='--code-editor-font: var(--default-mono-font, "GitLab Mono"), JetBrains Mono, Menlo, DejaVu Sans Mono, Liberation Mono, Consolas, Ubuntu Mono, Courier New, andale mono, lucida console, monospace;'>
<head>
<meta content="text/html; charset=US-ASCII" http-equiv="Content-Type">
<title>
GitLab
</title>
<style data-premailer="ignore" type="text/css">
a { color: #1068bf; }
</style>
<style>img {
max-width: 100%; height: auto;
}
body {
font-size: .875rem;
}
body {
-webkit-text-shadow: rgba(255,255,255,.01) 0 0 1px;
}
body {
font-family: var(--default-regular-font, "GitLab Sans"),-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"; font-size: inherit;
}
</style>
</head>
<body style='font-size: inherit; -webkit-text-shadow: rgba(255,255,255,.01) 0 0 1px; font-family: var(--default-regular-font, "GitLab Sans"),-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";'>
<div class="content">
<p class="details" style="font-style: italic; color: #737278;">
<a href="https://gitlab.rtems.org/amar">Amar Takhar</a> created an issue: <a href="https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/20">#20</a>
</p>
<div class="md" style="color: #333238; word-wrap: break-word;">
<h2 dir="auto" style="font-size: 1.5em; font-weight: 600; padding-bottom: .3em; border-bottom-width: 1px; border-bottom-color: #bfbfc3; border-bottom-style: solid; color: #333238; margin: 0 0 16px;" align="initial">
<a href="#summary" aria-hidden="true" class="anchor" id="user-content-summary" style="margin-top: 0; float: left; margin-left: -20px; text-decoration: none; outline: none;"></a>Summary</h2>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">We don't have any formal documentation about when an issue should be created. My proposal is to follow these two simple rules:</p>
<ul dir="auto" style="text-align: initial; list-style-type: disc; margin: 0 0 16px; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">If you need design and discussion before opening an MR create an issue.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">If you wish to collect multiple MRs for tracking create an issue or even better an <a href="https://docs.gitlab.com/ee/user/group/epics/" rel="nofollow noreferrer noopener" target="_blank" style="margin-top: 0;">epic</a>.</li>
</ul>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">Issues / tickets were important in the past because it allowed for tracking details related to a change.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">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.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">What we do lose by not having issues:</p>
<ul dir="auto" style="text-align: initial; list-style-type: disc; margin: 0 0 16px; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">It's harder to track a change in git back to the MR because <code style='font-size: 90%; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; vertical-align: bottom; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>git log</code> does not show the reverse connection.\
<ul style="list-style-type: circle; margin: 0; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">This is not a great solution as we've already lost track of some of these numbers see below.</li>
</ul>
</li>
</ul>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">A solution to the above problem is to annotate commits using <code style='font-size: 90%; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0; font-weight: inherit; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; vertical-align: bottom; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>git note</code>. 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.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">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.</p>
<p dir="auto" style="color: #333238; margin: 0;" align="initial"><a href="https://gitlab.rtems.org/chris" data-reference-type="user" data-user="3" data-container="body" data-placement="top" class="gfm gfm-project_member js-user-link" title="Chris Johns" style="background-color: #cbe2f9; border-radius: .25rem; color: #0b5cad; margin-top: 0; padding: 0 2px;">@chris</a> <a href="https://gitlab.rtems.org/gedare" data-reference-type="user" data-user="8" data-container="body" data-placement="top" class="gfm gfm-project_member js-user-link" title="Gedare Bloom" style="background-color: #cbe2f9; border-radius: .25rem; color: #0b5cad; padding: 0 2px;">@gedare</a> <a href="https://gitlab.rtems.org/opticron" data-reference-type="user" data-user="4" data-container="body" data-placement="top" class="gfm gfm-project_member js-user-link" title="Kinsey Moore" style="background-color: #cbe2f9; border-radius: .25rem; color: #0b5cad; padding: 0 2px;">@opticron</a> <a href="https://gitlab.rtems.org/joel" data-reference-type="user" data-user="7" data-container="body" data-placement="top" class="gfm gfm-project_member js-user-link" title="Joel Sherrill" style="background-color: #cbe2f9; border-radius: .25rem; color: #0b5cad; padding: 0 2px;">@joel</a></p>
</div>
</div>
<div class="footer" style="margin-top: 10px;">
<p style="font-size: small; color: #737278;">
—
<br>
<a href="https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/20">View it on GitLab</a>.
<br>
You're receiving this email because of your account on <a target="_blank" rel="noopener noreferrer" href="https://gitlab.rtems.org">gitlab.rtems.org</a>. <a href="https://gitlab.rtems.org/-/sent_notifications/f3863fbe7ae04b880e664f91c7feaf3e/unsubscribe" target="_blank" rel="noopener noreferrer">Unsubscribe</a> from this thread · <a href="https://gitlab.rtems.org/-/profile/notifications" target="_blank" rel="noopener noreferrer" class="mng-notif-link">Manage all notifications</a> · <a href="https://gitlab.rtems.org/help" target="_blank" rel="noopener noreferrer" class="help-link">Help</a>
<script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","action":{"@type":"ViewAction","name":"View Issue","url":"https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/20"}}</script>
</p>
</div>
</body>
</html>