Skip to content

Commit ca59bda

Browse files
levkowetzlevkowetz
committed
Templates for ietf-specific wiki pages
 - Legacy-Id: 12148
1 parent e7b7691 commit ca59bda

6 files changed

Lines changed: 376 additions & 0 deletions

File tree

‎ietf/templates/utils/wiki/IetfSpecificFeatures‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
= IETF-Specific Information =
2+
3+
== Editing the Wiki and Issues ==
4+
5+
In order to create and edit wiki pages and issues, you need to log in. Click on the
6+
small 'Login' link above the main horizontal menubar. You log in with the same
7+
username (your email address) and password as for all other ''tools.ietf.org'' password
8+
protected accesses. If you don't have a login/passwd or need to reset your passwd, go
9+
to http://tools.ietf.org/newpasswd .
10+
11+
The login and password is also used for commits to the SVN repository. See more about
12+
the repository further down.
13+
14+
== IETF-Specific Features ==
15+
16+
This Trac installation has a few IETF-specific features which are not generally found
17+
in Trac:
18+
19+
* Occurences of RFC numbers or draft names in Wiki text will generate links to the
20+
RFC or draft in question. Unless you want to point to an RFC or draft in a
21+
specific location which is different from the automatically generated link, you
22+
don't need to explicitly add links for RFCs and drafts. Examples: RFC 2026,
23+
draft-ietf-poised95-std-proc-3
24+
25+
* Each issue in the issue tracker can be indicated to concern a 'component'. This is
26+
a standard Trac feature; however, the list of available components is automatically
27+
updated to include all the active working group drafts. This makes it easier to
28+
associate issues with drafts for the WG participants, without the Chairs needing to
29+
go in as admin users and add a new component each time there's a new WG draft.
30+
31+
* The 'Severity' field of an issue has a special significance if the issue type is
32+
set to 'state' or 'task'. In that case, the Severity will be shown as an
33+
annotation to the draft state on the regular WG status page on tools.ietf.org.
34+
This can be useful for WG chairs to indicate more exactly the state of a WG draft,
35+
which will otherwise simply be indicated as 'Active' on the status page, until it
36+
is sent to the IESG for processing.
37+
38+
* If issues are registered against a draft ,indicated by setting the issue's
39+
'component' field to the appropriate (abbreviated) draft name, the status page
40+
will show a progress bar, indicating the total number of issues for that draft, as
41+
well as the proportion which have been closed, and the number of still open issues.
42+
43+
* Everywhere you can use wiki markup (on the wiki pages, roadmap descriptions,
44+
etc.) you may embed a macro which shows a ticket statistics graph. Full
45+
information about the macro is available at [http://trac-hacks.org/wiki/TicketStatsMacro].
46+
Briefly, the macro syntax is:
47+
{{{
48+
[[TicketStats( height=250,daterange=12m,res_days=30)]]
49+
}}}
50+
which gives this result: [[TicketStats( height=250,daterange=12m,res_days=30)]]
51+
52+
Issue tracker changes which are reflected in the WG status pages ('Severity'
53+
annotations and issue progress bars) may take up to 1 hour to propagate from the
54+
server which hosts the Trac instance (trac.tools.ietf.org) to the other tools servers.
55+
56+
== Integration with tools.ietf.org ==
57+
58+
For all working groups which have an instance of Trac installed, the URL to Trac for
59+
that WG has the form '''''!http://tools.ietf.org/wg/<wg>/trac'''''.
60+
There's also a link to the Trac issue tracker and a link to the Trac
61+
wiki in the horizontal menu on the WG status page
62+
'''''!http://tools.ietf.org/wg/<wg>'''''
63+
once Trac has been installed.
64+
65+
== SVN Repository ==
66+
67+
For each WG with a Trac instance there is also a SVN repository, with an URL of the
68+
form '''''!https://svn.tools.ietf.org/svn/wg/<wg>'''''. Anybody can check out from
69+
the repository, but you need to use the tools server login and password in order to
70+
commit to the repository.
71+
72+
To check out a repository with a command-line svn client, see this example for the ''hybi'' WG:
73+
74+
{{{
75+
work/ $ svn co --username=henrik@levkowetz.com https://svn.tools.ietf.org/svn/wg/hybi/
76+
work/ $ cd hybi/
77+
hybi/ $
78+
}}}
79+
80+
SVN also lets you check out parts of the repository tree, but for more info on
81+
that, please see the documentation on http://subversion.apache.org/.
82+
83+
To add a document to the repository, place the document in your SVN working folder,
84+
tell SVN it should be added, and when ready, commit it to the repository:
85+
{{{
86+
hybi/ $ svn add draft-foo-bar-baz.txt
87+
hybi/ $ #...
88+
hybi/ $ svn commit draft-foo-bar-baz.txt -m "Commit message ..."
89+
hybi/ $
90+
}}}
91+
92+
The IETF Trac instances use a variation of the Trac SVN hook script which is provided
93+
with Trac. This script updates Track Issue Tickets based on keywords in the SVN
94+
commit messages; the keywords and their use is described in SvnTracHooks.

‎ietf/templates/utils/wiki/InterMapTxt‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
= InterMapTxt =
2+
3+
== This is the place for defining InterWiki prefixes ==
4+
5+
This page was modelled after the MeatBall:InterMapTxt page.
6+
In addition, an optional comment is allowed after the mapping.
7+
8+
9+
This page is interpreted in a special way by Trac, in order to support
10+
!InterWiki links in a flexible and dynamic way.
11+
12+
The code block after the first line separator in this page
13+
will be interpreted as a list of !InterWiki specifications:
14+
{{{
15+
prefix <space> URL [<space> # comment]
16+
}}}
17+
18+
By using `$1`, `$2`, etc. within the URL, it is possible to create
19+
InterWiki links which support multiple arguments, e.g. Trac:ticket:40.
20+
The URL itself can be optionally followed by a comment,
21+
which will subsequently be used for decorating the links
22+
using that prefix.
23+
24+
New !InterWiki links can be created by adding to that list, in real time.
25+
Note however that ''deletions'' are also taken into account immediately,
26+
so it may be better to use comments for disabling prefixes.
27+
28+
Also note that !InterWiki prefixes are case insensitive.
29+
30+
31+
== List of Active Prefixes ==
32+
33+
[[InterWiki]]
34+
35+
36+
----
37+
38+
== Prefix Definitions ==
39+
40+
{{{
41+
PEP http://www.python.org/peps/pep-$1.html # Python Enhancement Proposal
42+
Trac-ML http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/ # Message $1 in Trac Mailing List
43+
trac-dev http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/ # Message $1 in Trac Development Mailing List
44+
45+
Mercurial http://www.selenic.com/mercurial/wiki/index.cgi/ # the wiki for the Mercurial distributed SCM
46+
47+
RFC http://tools.ietf.org/html/rfc$1.html # IETF's RFC $1
48+
DataTracker https://datatracker.ietf.org/doc/
49+
dt https://datatracker.ietf.org/doc/
50+
51+
#
52+
# A arbitrary pick of InterWiki prefixes...
53+
#
54+
Acronym http://www.acronymfinder.com/af-query.asp?String=exact&Acronym=
55+
C2find http://c2.com/cgi/wiki?FindPage&value=
56+
Cache http://www.google.com/search?q=cache:
57+
CPAN http://search.cpan.org/perldoc?
58+
DebianBug http://bugs.debian.org/
59+
DebianPackage http://packages.debian.org/
60+
Dictionary http://www.dict.org/bin/Dict?Database=*&Form=Dict1&Strategy=*&Query=
61+
Google http://www.google.com/search?q=
62+
GoogleGroups http://groups.google.com/group/$1/msg/$2 # Message $2 in $1 Google Group
63+
JargonFile http://downlode.org/perl/jargon-redirect.cgi?term=
64+
MeatBall http://www.usemod.com/cgi-bin/mb.pl?
65+
MetaWiki http://sunir.org/apps/meta.pl?
66+
MetaWikiPedia http://meta.wikipedia.org/wiki/
67+
MoinMoin http://moinmoin.wikiwikiweb.de/
68+
WhoIs http://www.whois.sc/
69+
Why http://clublet.com/c/c/why?
70+
c2Wiki http://c2.com/cgi/wiki?
71+
WikiPedia http://en.wikipedia.org/wiki/
72+
}}}

‎ietf/templates/utils/wiki/SvnTracHooks‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
= SVN Trac Hooks =
2+
3+
If the Trac Hooks for SVN has been installed for the svn repository
4+
coupled to this Trac instance, the Key Phrases documented below may
5+
be used in SVN commit messages to cause automatic updates and annotations
6+
of Trac issues.
7+
8+
== The trac-post-commit-hook ==
9+
10+
This script looks at the commit message associated with an SVN commit,
11+
and based on the presence of a number of key phrases will add annotations
12+
to tickets and also possibly change ticket status, for instance closing
13+
it.
14+
15+
=== Key Phrases ===
16+
17+
The key phrases available are:
18+
{{{
19+
Fix <ticket_spec>
20+
Fixes <ticket_spec>
21+
Fix for <ticket_spec>
22+
Close <ticket_spec>
23+
Closes <ticket_spec>
24+
25+
Addresses <ticket_spec>
26+
References <ticket_spec>
27+
Relates to <ticket_spec>
28+
Related to <ticket_spec>
29+
See <ticket_spec>
30+
}}}
31+
32+
=== Ticket specification ===
33+
34+
The specification of the ticket to act on may specify one or more
35+
tickets, using any of the following forms:
36+
{{{
37+
<ticket>
38+
<ticket>, <ticket>{, <ticket>}
39+
<ticket>, <ticket> and <ticket>
40+
}}}
41+
and variations thereof.
42+
43+
=== Ticket identification ===
44+
45+
The individual ticket specification
46+
can take any of the following forms:
47+
{{{
48+
#<number>
49+
ticket <number>
50+
ticket:<number>
51+
issue <number>
52+
issue:<number>
53+
bug <number>
54+
bug:<number>
55+
}}}
56+
57+
=== Examples ===
58+
59+
{{{
60+
Clarify header normalization vs matching request headers (see #147)
61+
62+
Resolve #27: fix definition of idempotent
63+
64+
Note change for issue 157 (related to #157)
65+
66+
Define http and https URI schemes: addresses #58, #128, #159
67+
68+
Define http and https URI schemes: addresses #58, #128, #159;
69+
fixes #157: removed reference to RFC1900 use of IP addresses in URI.
70+
71+
Resolve #140: rephrase note so that it becomes clear that the described ...
72+
}}}
73+
74+
=== Script ===
75+
76+
The default script installed as trac-post-commit-hook is:
77+
http://tools.ietf.org/tools/wg-pages/svn-hook-files/trac-post-commit-hook

‎ietf/templates/utils/wiki/ThisTracInstallation‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
{{{
2+
#!rst
3+
4+
Trac Installation on tools.ietf.org
5+
===================================
6+
7+
Background
8+
----------
9+
10+
The Track installation used on the tools.ietf.org site is different from the
11+
installation examples provided with Trac and on http://trac.edgewall.com. The
12+
reason is mainly that the multi-project examples all assume that Trac
13+
constitutes the whole of the deployed environment, rather than being part of a
14+
greater set. This means that the examples assume that accessing the
15+
individual projects through URLs of the form "/$some_path/trac/$projname"
16+
makes sense, while in our case, we would like the URLs to look like
17+
"/$some_path/$projname/trac". In the multi-project configuration, this would
18+
make Trac always believe that the project name is 'trac' - the last path
19+
component.
20+
21+
Explored Alternatives
22+
---------------------
23+
24+
Make Apache set ``TRAC_ENV`` dynamically
25+
........................................
26+
27+
Tell Apache to dynamically set Trac's environment variable ``TRAC_ENV`` to the
28+
particular value for the accessed project:
29+
30+
``/etc/apache2/sites-available/tools.ietf.org``:
31+
32+
::
33+
34+
ScriptAliasMatch "^/wg/[^/]+/trac(/.*)?" /usr/share/trac/cgi-bin/trac.cgi$1
35+
<LocationMatch "^/wg/([^/]+)/trac">
36+
SetEnv TRAC_ENV "/www/tools.ietf.org/tools/trac/wg/$1"
37+
</LocationMatch>
38+
39+
This doesn't work because Apache doesn't support $n replacements based on
40+
earlier LocationMatch matches.
41+
42+
Use .htaccess with default ScriptAlias
43+
......................................
44+
45+
Maybe we could use individual .htaccess files in each WG directory to set the
46+
``TRAC_ENV`` variable to the required value?
47+
48+
``/etc/apache2/sites-available/tools.ietf.org``:
49+
50+
::
51+
52+
ScriptAliasMatch "^/wg/[^/]+/trac(/.*)?" /usr/share/trac/cgi-bin/trac.cgi$1
53+
54+
55+
``/www/tools.ietf.org/wg/examplewg/.htaccess``:
56+
57+
::
58+
59+
SetEnv TRAC_ENV "/www/tools.ietf.org/wg/examplewg/trac"
60+
61+
This doesn't work because this .htaccess isn't read when ScriptAlias points to
62+
another directory.
63+
64+
65+
Use .htaccess with a local CGI script
66+
.....................................
67+
68+
Suppose we let ScriptAlias point to a script which is placed so that the
69+
.htaccess file actually gets read?
70+
71+
``/etc/apache2/sites-available/tools.ietf.org``:
72+
73+
::
74+
75+
ScriptAliasMatch "^/wg/([^/]+)/trac(/.*)?" /www/tools.ietf.org/wg/$1/trac/index.cgi$2
76+
77+
78+
``/www/tools.ietf.org/wg/examplewg/.htaccess``:
79+
80+
::
81+
82+
SetEnv TRAC_ENV "/www/tools.ietf.org/wg/examplewg/trac"
83+
84+
This *does* work, but it is not easily adapted to a Fast-CGI solution. It is
85+
the set-up which is currently in use, but an alternative which will permit
86+
fast-cgi usage would be preferred - the current solution is anything but
87+
snappy...
88+
89+
90+
91+
92+
93+
94+
}}}

‎ietf/templates/utils/wiki/TrainingMaterials‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
= Training Materials =
2+
3+
WG Traingin Materials go here.
4+
5+
If you want to embed video, you can use the ![[Movie(<url>,width=<width>,height=<height>)]]
6+
macro to embed moves from [http://youtube.com/ YouTube]. Suggested width and height parameters: width=640,height=385.
7+
8+
Example which doesn't point to an actual video:
9+
10+
[[Movie(http://www.youtube.com/watch?v=g_exampleid,width=640px,height=385px)]]

‎ietf/templates/utils/wiki/WikiStart‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
= Welcome to this IETF WG Trac installation =
2+
3+
Trac is a '''minimalistic''' approach to '''web-based''' project management,
4+
suitable for software and documentation projects and similar. Its goal is to
5+
simplify effective tracking and handling of project issues, enhancements and
6+
overall progress.
7+
8+
As all Wiki pages, this page is editable, this means that you can modify the
9+
contents of this page simply by using your web-browser. Simply click on the
10+
"Edit this page" link at the bottom of the page. WikiFormatting will give you
11+
a detailed description of available Wiki formatting commands.
12+
13+
There is nothing in this page which isn't also covered in one of the other
14+
wiki pages, so the first adjustment you make of this Trac installation could
15+
be to edit the content of this page, replacing this initial text with content
16+
appropriate to your Working Group.
17+
18+
There are some aspects of this Trac installation which are specific to the
19+
IETF environment. Those are described in IetfSpecificFeatures.
20+
21+
22+
== Starting Points ==
23+
24+
* TracGuide -- Built-in Documentation
25+
* [http://trac.edgewall.org/ The Trac project] -- Trac Open Source Project
26+
* [http://trac.edgewall.org/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions
27+
* TracSupport -- Trac Support
28+
29+
For a complete list of local wiki pages, see TitleIndex.

0 commit comments

Comments
 (0)