From ca59bdac774d3a6e41d59c4a9e2e6aca7263dac7 Mon Sep 17 00:00:00 2001 From: Henrik Levkowetz Date: Fri, 14 Oct 2016 14:59:49 +0000 Subject: [PATCH] Templates for ietf-specific wiki pages - Legacy-Id: 12148 --- .../templates/utils/wiki/IetfSpecificFeatures | 94 +++++++++++++++++++ ietf/templates/utils/wiki/InterMapTxt | 72 ++++++++++++++ ietf/templates/utils/wiki/SvnTracHooks | 77 +++++++++++++++ .../templates/utils/wiki/ThisTracInstallation | 94 +++++++++++++++++++ ietf/templates/utils/wiki/TrainingMaterials | 10 ++ ietf/templates/utils/wiki/WikiStart | 29 ++++++ 6 files changed, 376 insertions(+) create mode 100644 ietf/templates/utils/wiki/IetfSpecificFeatures create mode 100644 ietf/templates/utils/wiki/InterMapTxt create mode 100644 ietf/templates/utils/wiki/SvnTracHooks create mode 100644 ietf/templates/utils/wiki/ThisTracInstallation create mode 100644 ietf/templates/utils/wiki/TrainingMaterials create mode 100644 ietf/templates/utils/wiki/WikiStart diff --git a/ietf/templates/utils/wiki/IetfSpecificFeatures b/ietf/templates/utils/wiki/IetfSpecificFeatures new file mode 100644 index 000000000..62502bc84 --- /dev/null +++ b/ietf/templates/utils/wiki/IetfSpecificFeatures @@ -0,0 +1,94 @@ += IETF-Specific Information = + +== Editing the Wiki and Issues == + +In order to create and edit wiki pages and issues, you need to log in. Click on the +small 'Login' link above the main horizontal menubar. You log in with the same +username (your email address) and password as for all other ''tools.ietf.org'' password +protected accesses. If you don't have a login/passwd or need to reset your passwd, go +to http://tools.ietf.org/newpasswd . + +The login and password is also used for commits to the SVN repository. See more about +the repository further down. + +== IETF-Specific Features == + +This Trac installation has a few IETF-specific features which are not generally found +in Trac: + + * Occurences of RFC numbers or draft names in Wiki text will generate links to the + RFC or draft in question. Unless you want to point to an RFC or draft in a + specific location which is different from the automatically generated link, you + don't need to explicitly add links for RFCs and drafts. Examples: RFC 2026, + draft-ietf-poised95-std-proc-3 + + * Each issue in the issue tracker can be indicated to concern a 'component'. This is + a standard Trac feature; however, the list of available components is automatically + updated to include all the active working group drafts. This makes it easier to + associate issues with drafts for the WG participants, without the Chairs needing to + go in as admin users and add a new component each time there's a new WG draft. + + * The 'Severity' field of an issue has a special significance if the issue type is + set to 'state' or 'task'. In that case, the Severity will be shown as an + annotation to the draft state on the regular WG status page on tools.ietf.org. + This can be useful for WG chairs to indicate more exactly the state of a WG draft, + which will otherwise simply be indicated as 'Active' on the status page, until it + is sent to the IESG for processing. + + * If issues are registered against a draft ,indicated by setting the issue's + 'component' field to the appropriate (abbreviated) draft name, the status page + will show a progress bar, indicating the total number of issues for that draft, as + well as the proportion which have been closed, and the number of still open issues. + + * Everywhere you can use wiki markup (on the wiki pages, roadmap descriptions, + etc.) you may embed a macro which shows a ticket statistics graph. Full + information about the macro is available at [http://trac-hacks.org/wiki/TicketStatsMacro]. + Briefly, the macro syntax is: + {{{ + [[TicketStats( height=250,daterange=12m,res_days=30)]] + }}} + which gives this result: [[TicketStats( height=250,daterange=12m,res_days=30)]] + +Issue tracker changes which are reflected in the WG status pages ('Severity' +annotations and issue progress bars) may take up to 1 hour to propagate from the +server which hosts the Trac instance (trac.tools.ietf.org) to the other tools servers. + +== Integration with tools.ietf.org == + +For all working groups which have an instance of Trac installed, the URL to Trac for +that WG has the form '''''!http://tools.ietf.org/wg//trac'''''. +There's also a link to the Trac issue tracker and a link to the Trac +wiki in the horizontal menu on the WG status page +'''''!http://tools.ietf.org/wg/''''' +once Trac has been installed. + +== SVN Repository == + +For each WG with a Trac instance there is also a SVN repository, with an URL of the +form '''''!https://svn.tools.ietf.org/svn/wg/'''''. Anybody can check out from +the repository, but you need to use the tools server login and password in order to +commit to the repository. + +To check out a repository with a command-line svn client, see this example for the ''hybi'' WG: + +{{{ +work/ $ svn co --username=henrik@levkowetz.com https://svn.tools.ietf.org/svn/wg/hybi/ +work/ $ cd hybi/ +hybi/ $ +}}} + +SVN also lets you check out parts of the repository tree, but for more info on +that, please see the documentation on http://subversion.apache.org/. + +To add a document to the repository, place the document in your SVN working folder, +tell SVN it should be added, and when ready, commit it to the repository: +{{{ +hybi/ $ svn add draft-foo-bar-baz.txt +hybi/ $ #... +hybi/ $ svn commit draft-foo-bar-baz.txt -m "Commit message ..." +hybi/ $ +}}} + +The IETF Trac instances use a variation of the Trac SVN hook script which is provided +with Trac. This script updates Track Issue Tickets based on keywords in the SVN +commit messages; the keywords and their use is described in SvnTracHooks. diff --git a/ietf/templates/utils/wiki/InterMapTxt b/ietf/templates/utils/wiki/InterMapTxt new file mode 100644 index 000000000..cdd997a71 --- /dev/null +++ b/ietf/templates/utils/wiki/InterMapTxt @@ -0,0 +1,72 @@ += InterMapTxt = + +== This is the place for defining InterWiki prefixes == + +This page was modelled after the MeatBall:InterMapTxt page. +In addition, an optional comment is allowed after the mapping. + + +This page is interpreted in a special way by Trac, in order to support +!InterWiki links in a flexible and dynamic way. + +The code block after the first line separator in this page +will be interpreted as a list of !InterWiki specifications: +{{{ +prefix URL [ # comment] +}}} + +By using `$1`, `$2`, etc. within the URL, it is possible to create +InterWiki links which support multiple arguments, e.g. Trac:ticket:40. +The URL itself can be optionally followed by a comment, +which will subsequently be used for decorating the links +using that prefix. + +New !InterWiki links can be created by adding to that list, in real time. +Note however that ''deletions'' are also taken into account immediately, +so it may be better to use comments for disabling prefixes. + +Also note that !InterWiki prefixes are case insensitive. + + +== List of Active Prefixes == + +[[InterWiki]] + + +---- + +== Prefix Definitions == + +{{{ +PEP http://www.python.org/peps/pep-$1.html # Python Enhancement Proposal +Trac-ML http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/ # Message $1 in Trac Mailing List +trac-dev http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/ # Message $1 in Trac Development Mailing List + +Mercurial http://www.selenic.com/mercurial/wiki/index.cgi/ # the wiki for the Mercurial distributed SCM + +RFC http://tools.ietf.org/html/rfc$1.html # IETF's RFC $1 +DataTracker https://datatracker.ietf.org/doc/ +dt https://datatracker.ietf.org/doc/ + +# +# A arbitrary pick of InterWiki prefixes... +# +Acronym http://www.acronymfinder.com/af-query.asp?String=exact&Acronym= +C2find http://c2.com/cgi/wiki?FindPage&value= +Cache http://www.google.com/search?q=cache: +CPAN http://search.cpan.org/perldoc? +DebianBug http://bugs.debian.org/ +DebianPackage http://packages.debian.org/ +Dictionary http://www.dict.org/bin/Dict?Database=*&Form=Dict1&Strategy=*&Query= +Google http://www.google.com/search?q= +GoogleGroups http://groups.google.com/group/$1/msg/$2 # Message $2 in $1 Google Group +JargonFile http://downlode.org/perl/jargon-redirect.cgi?term= +MeatBall http://www.usemod.com/cgi-bin/mb.pl? +MetaWiki http://sunir.org/apps/meta.pl? +MetaWikiPedia http://meta.wikipedia.org/wiki/ +MoinMoin http://moinmoin.wikiwikiweb.de/ +WhoIs http://www.whois.sc/ +Why http://clublet.com/c/c/why? +c2Wiki http://c2.com/cgi/wiki? +WikiPedia http://en.wikipedia.org/wiki/ +}}} diff --git a/ietf/templates/utils/wiki/SvnTracHooks b/ietf/templates/utils/wiki/SvnTracHooks new file mode 100644 index 000000000..79c7cbd72 --- /dev/null +++ b/ietf/templates/utils/wiki/SvnTracHooks @@ -0,0 +1,77 @@ += SVN Trac Hooks = + +If the Trac Hooks for SVN has been installed for the svn repository +coupled to this Trac instance, the Key Phrases documented below may +be used in SVN commit messages to cause automatic updates and annotations +of Trac issues. + +== The trac-post-commit-hook == + +This script looks at the commit message associated with an SVN commit, +and based on the presence of a number of key phrases will add annotations +to tickets and also possibly change ticket status, for instance closing +it. + +=== Key Phrases === + +The key phrases available are: +{{{ + Fix + Fixes + Fix for + Close + Closes + + Addresses + References + Relates to + Related to + See +}}} + +=== Ticket specification === + +The specification of the ticket to act on may specify one or more +tickets, using any of the following forms: +{{{ + + , {, } + , and +}}} +and variations thereof. + +=== Ticket identification === + +The individual ticket specification +can take any of the following forms: +{{{ + # + ticket + ticket: + issue + issue: + bug + bug: +}}} + +=== Examples === + +{{{ + Clarify header normalization vs matching request headers (see #147) + + Resolve #27: fix definition of idempotent + + Note change for issue 157 (related to #157) + + Define http and https URI schemes: addresses #58, #128, #159 + + Define http and https URI schemes: addresses #58, #128, #159; + fixes #157: removed reference to RFC1900 use of IP addresses in URI. + + Resolve #140: rephrase note so that it becomes clear that the described ... +}}} + +=== Script === + +The default script installed as trac-post-commit-hook is: +http://tools.ietf.org/tools/wg-pages/svn-hook-files/trac-post-commit-hook diff --git a/ietf/templates/utils/wiki/ThisTracInstallation b/ietf/templates/utils/wiki/ThisTracInstallation new file mode 100644 index 000000000..454c3f7c8 --- /dev/null +++ b/ietf/templates/utils/wiki/ThisTracInstallation @@ -0,0 +1,94 @@ +{{{ +#!rst + +Trac Installation on tools.ietf.org +=================================== + +Background +---------- + +The Track installation used on the tools.ietf.org site is different from the +installation examples provided with Trac and on http://trac.edgewall.com. The +reason is mainly that the multi-project examples all assume that Trac +constitutes the whole of the deployed environment, rather than being part of a +greater set. This means that the examples assume that accessing the +individual projects through URLs of the form "/$some_path/trac/$projname" +makes sense, while in our case, we would like the URLs to look like +"/$some_path/$projname/trac". In the multi-project configuration, this would +make Trac always believe that the project name is 'trac' - the last path +component. + +Explored Alternatives +--------------------- + +Make Apache set ``TRAC_ENV`` dynamically +........................................ + +Tell Apache to dynamically set Trac's environment variable ``TRAC_ENV`` to the +particular value for the accessed project: + +``/etc/apache2/sites-available/tools.ietf.org``: + +:: + + ScriptAliasMatch "^/wg/[^/]+/trac(/.*)?" /usr/share/trac/cgi-bin/trac.cgi$1 + + SetEnv TRAC_ENV "/www/tools.ietf.org/tools/trac/wg/$1" + + +This doesn't work because Apache doesn't support $n replacements based on +earlier LocationMatch matches. + +Use .htaccess with default ScriptAlias +...................................... + +Maybe we could use individual .htaccess files in each WG directory to set the +``TRAC_ENV`` variable to the required value? + +``/etc/apache2/sites-available/tools.ietf.org``: + +:: + + ScriptAliasMatch "^/wg/[^/]+/trac(/.*)?" /usr/share/trac/cgi-bin/trac.cgi$1 + + +``/www/tools.ietf.org/wg/examplewg/.htaccess``: + +:: + + SetEnv TRAC_ENV "/www/tools.ietf.org/wg/examplewg/trac" + +This doesn't work because this .htaccess isn't read when ScriptAlias points to +another directory. + + +Use .htaccess with a local CGI script +..................................... + +Suppose we let ScriptAlias point to a script which is placed so that the +.htaccess file actually gets read? + +``/etc/apache2/sites-available/tools.ietf.org``: + +:: + + ScriptAliasMatch "^/wg/([^/]+)/trac(/.*)?" /www/tools.ietf.org/wg/$1/trac/index.cgi$2 + + +``/www/tools.ietf.org/wg/examplewg/.htaccess``: + +:: + + SetEnv TRAC_ENV "/www/tools.ietf.org/wg/examplewg/trac" + +This *does* work, but it is not easily adapted to a Fast-CGI solution. It is +the set-up which is currently in use, but an alternative which will permit +fast-cgi usage would be preferred - the current solution is anything but +snappy... + + + + + + +}}} diff --git a/ietf/templates/utils/wiki/TrainingMaterials b/ietf/templates/utils/wiki/TrainingMaterials new file mode 100644 index 000000000..5c1622933 --- /dev/null +++ b/ietf/templates/utils/wiki/TrainingMaterials @@ -0,0 +1,10 @@ += Training Materials = + +WG Traingin Materials go here. + +If you want to embed video, you can use the ![[Movie(,width=,height=)]] +macro to embed moves from [http://youtube.com/ YouTube]. Suggested width and height parameters: width=640,height=385. + +Example which doesn't point to an actual video: + +[[Movie(http://www.youtube.com/watch?v=g_exampleid,width=640px,height=385px)]] diff --git a/ietf/templates/utils/wiki/WikiStart b/ietf/templates/utils/wiki/WikiStart new file mode 100644 index 000000000..44bdc9ff4 --- /dev/null +++ b/ietf/templates/utils/wiki/WikiStart @@ -0,0 +1,29 @@ += Welcome to this IETF WG Trac installation = + +Trac is a '''minimalistic''' approach to '''web-based''' project management, +suitable for software and documentation projects and similar. Its goal is to +simplify effective tracking and handling of project issues, enhancements and +overall progress. + +As all Wiki pages, this page is editable, this means that you can modify the +contents of this page simply by using your web-browser. Simply click on the +"Edit this page" link at the bottom of the page. WikiFormatting will give you +a detailed description of available Wiki formatting commands. + +There is nothing in this page which isn't also covered in one of the other +wiki pages, so the first adjustment you make of this Trac installation could +be to edit the content of this page, replacing this initial text with content +appropriate to your Working Group. + +There are some aspects of this Trac installation which are specific to the +IETF environment. Those are described in IetfSpecificFeatures. + + +== Starting Points == + + * TracGuide -- Built-in Documentation + * [http://trac.edgewall.org/ The Trac project] -- Trac Open Source Project + * [http://trac.edgewall.org/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions + * TracSupport -- Trac Support + +For a complete list of local wiki pages, see TitleIndex.