<!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: "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: "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 style="color: #777777;">
<a href="https://gitlab.rtems.org/Opifex">W S</a>
commented on a
<a href="https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/108#note_117531">discussion</a>:
</p>
<div class="md" style="position: relative; z-index: 1; color: #28272d; word-wrap: break-word;">
<blockquote dir="auto" style="font-size: inherit; color: #4c4b51; padding-top: .5rem; padding-bottom: .5rem; padding-left: 1rem; border-left-color: #dcdcde; border-left-style: solid; margin: 0 0 .5rem; border-width: 0 0 0 4px;" align="initial">
<p style="color: inherit; line-height: 1.5; margin: 0;">Would you like to make the collection?</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">What do you mean? It's already made, isn't it?</p>
<blockquote dir="auto" style="font-size: inherit; color: #4c4b51; padding-top: .5rem; padding-bottom: .5rem; padding-left: 1rem; border-left-color: #dcdcde; border-left-style: solid; margin: .5rem 0; border-width: 0 0 0 4px;" align="initial">
<p style="color: inherit; line-height: 1.5; margin: 0;">Maybe I am not understanding the purpose of the list. If the docs build does it matter if the version of the packages used is not an exact match? I can see a role for a list that is equal or greater than a version as we do require some packages be at a specific level.</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">The purpose of the list is to:</p>
<ol dir="auto" style="text-align: initial; margin: 0 0 16px; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">Give anyone who wishes to run the software (in this case the docs builder) a very convenient way to install the required dependencies. They do not need to figure out how it can be done on their specific environment. The README already specifies some instructions on how to install them, but of course they can't cover all possible environments, machines and operating systems. They are also bound to break at one point or another, when packages are removed or renamed from those repositories, or when technologies change. A Python virtualenvironment in combination with pip and a requirements.txt prevents this. It is supposed to work indefinitely.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">Prevent future updated packages from silently (or not silently) breaking things.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">Guarantee that everyone who builds the software (docs in this case) has the exact same outcome. Maybe version 1.1 of package foo draws a green circle, while version 1.2 draws a red circle. Maybe 1.3 won't build anymore at all. That's not desirable of course.</li>
</ol>
<blockquote dir="auto" style="font-size: inherit; color: #4c4b51; padding-top: .5rem; padding-bottom: .5rem; padding-left: 1rem; border-left-color: #dcdcde; border-left-style: solid; margin: .5rem 0; border-width: 0 0 0 4px;" align="initial">
<p style="color: inherit; line-height: 1.5; margin: 0;">The other issue with a list is who maintains it?</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">That's the beauty of it. It doesn't need maintaining. You can stick with the frozen versions of the packages because those are known to work. Only if someone wishes to use a new feature of a used package (or if they wish to use an entirely new package) they will have to update the requirements.txt. It will be their responsibility to figure out what new configuration works with whatever it is they wish to do.</p>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">This might sound a lot of work for this individual. Sure. But think of the alternative: he installs some version on his system that work for him. The docs build, they look fine. He pushes and the commit gets merged. Then... it appears that no one else can reproduce what he did? Everyone else now has to figure out what configuration they have to install to get it working.</p>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">Of course, this last part is a worst case scenario and is unlikely to happen. Especially not for a repository that only builds some docs. Like amar said: it hasn't broken out of itself for 10+ years and is unlikely to break in the near future. Yet, this approach is pretty much standard in any FOSS project that uses Python. For the reasons described above.</p>
<p dir="auto" style="color: #28272d; margin: 0;" align="initial">(all that being said: this really is becoming bikeshedding <gl-emoji title="smiling face with open mouth and smiling eyes" data-name="smile" data-unicode-version="6.0" style="margin-top: 0;">😄</gl-emoji> It's just docs, it's not a hill to die on :D )</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/-/merge_requests/108#note_117531">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/2a3974363c82461ec79ce56ef427fe94/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 Merge request","url":"https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/108#note_117531"}}</script>
</p>
</div>
</body>
</html>