On 2020-09-25 17:55, Ryan Schmidt wrote:
On Sep 25, 2020, at 18:50, MacPorts Wiki wrote:
Page "WikiFormatting" was changed by JDLH
Diff URL: <https://trac.macports.org/wiki/WikiFormatting?action=diff&version=7>
Revision 7
Comment: Add example of GitHub commit link with abbreviation
On Sep 25, 2020, at 19:33, MacPorts Wiki wrote:
Page "TracLinks" was changed by JDLH
Diff URL: <https://trac.macports.org/wiki/TracLinks?action=diff&version=8>
Revision 8
Comment: Describe GitHub commit links including abbreviation in link text. New section
"Links to MacPorts on GitHub"
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:
https://trac.edgewall.org/wiki/TracUpgrade#UpdatetheTracDocumentation
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.
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.)
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.
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.
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.
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).
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.
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.
As another path to getting the word out about changeset references to
GitHub, I also created PR#41 /Describe GitHub changeset links in 7.1.3
Trac Ticket Guidelines/
<https://github.com/macports/macports-guide/pull/41>. 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?
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.
Cheers,
—Jim DeLaHunt
