<!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: 0.875rem;
}
body {
-webkit-text-shadow: rgba(255,255,255,0.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,0.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 style="color: #777777;">
<a href="https://gitlab.com/skyvine">Skyler Ferris</a>
<a href="https://gitlab.com/gnutls/guile/-/issues/16#note_1521480551">commented</a>:
</p>
<div class="md" style="color: #333238; word-wrap: break-word;">
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">I started working on this. It's very "rough draft" right now, but <a href="https://gitlab.com/skyvine/guile-gnutls/-/commit/c27a24ed36f6a681616a5250b8d95c923b86a0a8" data-reference-type="commit" data-original="it shows my intentions" data-link="true" data-link-reference="true" data-project="48649120" data-commit="c27a24ed36f6a681616a5250b8d95c923b86a0a8" data-container="body" data-placement="top" title="WIP: Refactor examples to be testable & test them" class="gfm gfm-commit has-tooltip" style='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; font-variant-ligatures: none; font-size: 95%; margin-top: 0;'>it shows my intentions</a>. I haven't used autotools before so I might need some help understanding how to modify those scripts. In the meantime, I added a phase to <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>guix.scm</code> so I could try it.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">I want to be able to split this change across multiple commits without breaking the build on any individual commit. This is why the build phase checks if <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>main</code> is defined before calling it. Unfortunately, this does not work with the examples as-is, because some of them expect interactive input.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">There are 2 competing concerns here. On one hand, we want the examples to be testable to make sure that people have accurate information. On the other hand, we want the examples to be easily understood by people who are unfamiliar with the GNUTLS API, and possibly new to TLS itself. This means that the examples should not only be readable, but also easy to modify for the purpose of exploring the library. I assume that the latter concern is the reason that some of the examples have interactive input.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">The convention demonstrated in the WIP commit is for each example to define a <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>main</code> function which takes an <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>#:automated?</code> argument that defaults to false. This way if a person runs it without reading it fully (I know, but the reality is that people do that, particularly when testing an unfamiliar project for usability) then it will behave in the way that is most useful to them. The build system will pass <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>#:automated? #t</code>.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">Accounting for both of these concerns does degrade the quality of the code in terms of maintainability and explorability. However, I think that if the code is written with these concerns in mind the impact can be minimized. In general, I would prefer additional cognitive load for testing rather than exploring. The tester is presumably better equipped to manage it than the explorer, who is in an unfamiliar environment.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">I propose the following series of commits:</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;">A set of commits which updates each example currently in <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>guile/examples</code> to use the <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>main #:automated?</code> convention.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">A commit which updates autotools to run something equivalent to the build phase in the WIP commit.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">A set of commits which moves each example from the manual into <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>guile/examples</code>.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">Possibly, commits to add examples currently in <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; 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; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>guile/examples</code> to the manual.</li>
</ol>
<p dir="auto" style="color: #333238; margin: 0;" align="initial">If this sounds good to you, I could send commits as I complete them or open a single merge request once everything is done, whatever works better on your end. I am working on this in my spare time, so it might take a while to complete it all.</p>
</div>
</div>
<div class="footer" style="margin-top: 10px;">
<p style="font-size: small; color: #737278;">
—
<br>
Reply to this email directly or <a href="https://gitlab.com/gnutls/guile/-/issues/16#note_1521480551">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.com">gitlab.com</a>. <a href="https://gitlab.com/-/sent_notifications/65b3ffd8e33a913562640d0c152f8bac/unsubscribe" target="_blank" rel="noopener noreferrer">Unsubscribe</a> from this thread · <a href="https://gitlab.com/-/profile/notifications" target="_blank" rel="noopener noreferrer" class="mng-notif-link">Manage all notifications</a> · <a href="https://gitlab.com/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.com/gnutls/guile/-/issues/16#note_1521480551"}}</script>
</p>
</div>
</body>
</html>