<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
On 2020-09-25 17:55, Ryan Schmidt wrote:<br>
<blockquote type="cite"
cite="mid:26CD664E-C592-4E22-89F7-3538BAA91AB3@macports.org">
<pre class="moz-quote-pre" wrap="">On Sep 25, 2020, at 18:50, MacPorts Wiki wrote:
</pre>
<blockquote type="cite">
<pre class="moz-quote-pre" wrap="">
Page "WikiFormatting" was changed by JDLH
Diff URL: <a class="moz-txt-link-rfc2396E" href="https://trac.macports.org/wiki/WikiFormatting?action=diff&version=7"><https://trac.macports.org/wiki/WikiFormatting?action=diff&version=7></a>
Revision 7
Comment: Add example of GitHub commit link with abbreviation
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">
On Sep 25, 2020, at 19:33, MacPorts Wiki wrote:
</pre>
<blockquote type="cite">
<pre class="moz-quote-pre" wrap="">Page "TracLinks" was changed by JDLH
Diff URL: <a class="moz-txt-link-rfc2396E" href="https://trac.macports.org/wiki/TracLinks?action=diff&version=8"><https://trac.macports.org/wiki/TracLinks?action=diff&version=8></a>
Revision 8
Comment: Describe GitHub commit links including abbreviation in link text. New section "Links to MacPorts on GitHub"
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">
Jim, as I mentioned when you asked on the list a couple weeks ago, we should not edit the standard Trac documentation pages. Your changes will be lost the next time we update Trac:
<a class="moz-txt-link-freetext" href="https://trac.edgewall.org/wiki/TracUpgrade#UpdatetheTracDocumentation">https://trac.edgewall.org/wiki/TracUpgrade#UpdatetheTracDocumentation</a>
We should delete your changed versions and mark the pages as read-only, which is apparently a thing that can be done and is done by default on new Trac installs these days.
</pre>
</blockquote>
<p>Thank you for your prompt reply, Ryan. (An example of the huge
amount of attention and effort you put into MacPorts overall, for
which we are all grateful.)<br>
</p>
<p>I thought about this, and was about to reply to my macports-users
message with a report on what I did and why. I think making these
changes is the best way forward overall.<br>
</p>
<p>I agree that these changes will be overwritten (not lost, they
should be in the edit history) when the Trac documentation gets
updated, probably when the next Trac upgrade gets deployed. But,
1) how long until that happens? From the edit history, it might
be months or years. 2) until that happens, these changes benefit
people who look at the wiki pages WikiFormatting and TracLinks.</p>
<p>The other part of the change, which I wanted to make, is to
create a new wiki page LocalTracGuideChanges . I apparently don't
have authority to create this page. I would propose that this page
has a record of all edits made to the Trac Guide wiki pages, so
that when an upgrade happens and the installer overwrites these
pages, we have a concise list from which to re-apply the
customisations. LocalTracGuideChanges can link to Trac wiki diff
URLs, or have the literal wiki text of the change. <br>
</p>
<p>I wrote the changes so that they occupy complete lines of wiki
text. That should make the changes easier to apply (though it
doesn't protect us if Trac changes the content structure in the
new version).</p>
<p>The drawback to the way Trac structures the Guide is that the
Trac software affords local ajustment of features, e.g. GitHub
support, but does not afford local adjustment of the documentation
describing those features.</p>
<p>As an alternative, we could make our own pages
WikiFormattingMacPorts and TracLinksMacPorts, with our
customisations, and links to the Trac-supplied WikiFormatting and
TracLinks pages. We could change the MacPorts Guide to refer to
our own pages. I don't know if we can change the New Ticket window
to refer to our own pages instead of the Trac standard pages.</p>
<p>As another path to getting the word out about changeset
references to GitHub, I also created PR#41 <i>Describe GitHub
changeset links in 7.1.3 Trac Ticket Guidelines</i> <<a
moz-do-not-send="true"
href="https://github.com/macports/macports-guide/pull/41">https://github.com/macports/macports-guide/pull/41</a>>.
This mentions the GitHub changeset link syntax concisely. It would
still be nice to link to some documentation somewhere with more
detail. The current PR links to wiki page TracLinks. Maybe put all
the detail somewhere in the Guide?</p>
<p>So, while I understand your concern about the content getting
overwritten, I think it's also important to put the content
somewhere where people can see it. Trac has blocked off the best
structures, so we are left with second-best.</p>
<p>Cheers,<br>
—Jim DeLaHunt<br>
</p>
<p><br>
</p>
<p><br>
</p>
</body>
</html>