<!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_117627">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;">Until someone comes along with a distro or OS version that can only run newer versions of some of the packages than are on the list.</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">AFAIK that should not be possible. The venv is supposed to prevent this. The only issue I can potentially see is a future Python version causing compatibility problems. A solution for that would be to freeze the Python version as well, but that can't be done through the requirements.txt. I also would not recommend it at this point. Because this <strong style="font-weight: 600; margin-top: 0;">would</strong> create a hassle for new, non-technical users.</p>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">(P.s. note that without the use of the requirements.txt this can also be an issue: the main RTEMS repository currently is sort of broken for Python3.12 and up. I know the issue has been mentioned a couple of times on Discord, but as far as I can tell no one has made an Issue yet. I will try to create one later today, because I was one of the affected users :) )</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;">They're probably a newcomer and not an expert on your documentation build system, so they have no idea how to fix the configuration.</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">Which is precisely why this list comes in handy. It gives the non-expert a beginner friendly and failsafe way of installing packages, instead of digging through a README that may or may not have up-to-date and complete instructions on how to install it on their OS.</p>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">(Note that they don't <em style="margin-top: 0;">have</em> to use it. If they want to do it the hard way, they're still free to do so. This requirements.txt merely provides a pythonic and standardized way of installing the packages)</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;">The packages building the docs for the release documentation do not match this list. We can tolerate older versions of some packages than in this list.</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">The requirements.txt of this PR was made based on the README. However, I indeed did not pay attention to the versions specified in that document. (Note that the instructions on how to install them also will not install the specified versions!)</p>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">I guess it would be a fair request to let the versions of the requirements.txt match the ones of the README.</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;">It will need maintaining over time. We have had to raise the base level of sphinx a few times because of breakages.</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">Can you explain how it broke? I can only think of three ways it can break:</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;">The package was updated, causing things that worked before to no longer work as expected</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">Another package was updated, causing a conflict with the package that broke</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">Someone made a change, which turned out to create an undesired effect. Updating solved it.</li>
</ol>
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial">Case 1 and 2 would have been prevented by pinned versions in a requirements.txt. Case 3 can always happen, regardless of using pinned versions or not, regardless of using a requirements.txt or not. It will always be a responsibility of the one making a change to make sure that he does not break anything, and if he does, he fixes it.
Active maintenance of this file is not needed and even not desired. It would do more harm than good. It should only be updated when there is an actual need for a change.</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;">Please do not get me wrong, I like idea of a list so I am wanting to understand the liabilities the project accepts if we merge it.</p>
</blockquote>
<p dir="auto" style="color: #28272d; margin: 0;" align="initial">Don't worry. I don't mind explaining things :) But on the other hand, I'm also aware that I'm not an all-knowing super-being that's always right. So after explaining my position, I will accept you guys' consensus without any resistance <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></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_117627">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/86fc0054f72b6b30c2b54c777b206e99/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_117627"}}</script>
</p>
</div>
</body>
</html>