[MacPorts] WikiFormatting modified

[Jim DeLaHunt]

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



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macports.org/pipermail/macports-users/attachments/20200925/b1e92efa/attachment.htm>