On 20/02/13 18:54, Daniel Shahaf wrote:
Gabriela Gibson wrote on Wed, Feb 20, 2013 at 16:22:36 +0000:
On 20/02/13 15:28, Gabriela Gibson wrote:
+++ publish/.htaccess (working copy)
@@ -1,7 +1,6 @@
# duplicated in httpd.conf in r795618
Options +Includes
-XBitHack On
RedirectMatch ^/buildbot(.*) http://ci.apache.org/waterfall?\
\&show=bb-openbsd\
\&show=svn-slik-w2k3-x64-local\
You might want to commit this part separately? It isn't as much related
to the other changes as something we found while working on them.
True. Removed and queued.
+++ publish/docs/community-guide/community-guide.html (working copy)
@@ -73,6 +77,7 @@ first.</p>
You seem to have added "web" before "debugging" here, while it's after
"debugging" everywhere else.
Oops. Thanks, and well spotted!
+++ publish/docs/community-guide/web.part.html (revision 0)
A couple of minor comments about this file:
+<p>Putting it all together, an example VirtualHost configuration is:</p>
+
+<pre><VirtualHost *:8080>
+ ServerAdmin webmaster@localhost
Consider putting this example in a separate *.conf file, to make it
easier to reuse?
I've left it on for now, but I'm wondering if you find it too spammy
this way or it's just the convenience of the *.conf file? We can do
both, but indeed, there is a lot to be said for brevity.
'diff -u ~/projects/svn/site/**/svnsite.conf /etc/apache2/svnsite.conf'
+<p>then upload the resulting file to a HTML validatory, for
"validatory"?
Yes :) It's an unusual but technically correct term. I've left it in
for now, because one thing about documentation is that it's a little
boring to read, and interesting wording helps people remember things
easier.
Addition of section to Community Guide describing procedure for
Use the imperative: "Add a section"
Fixed.
You didn't include README in the patch.
Oops. Fixed. Forgot to 'svn add'.
Bottom line: once the points about README and .htaccess are addressed,
Done.
+1 to commit. (Everything else can be addressed post-commit if you
disagree with the review.) Thanks or the patch!
To sum up:
1) .htaccess and permission changes will go into a separate patch.
2) With view to a further patch, the term 'Validatory' is still being
discussed, and we need to decide is the conf stays on the page and/or is
moved to it's own file, linked from this spot.
[[[
Add a section to Community Guide describing procedure for obtaining
the source for the Subversion web site. Addition of navigation links
to new page within community guide.
Add three html files creating one extra page on web site accessible at
/docs/community-guide/web.html. Also add README in top level directory
providing link to new web page.
* publish/docs/community-guide/web.html
(New page): Provide the top-level html page for the new page.
* publish/docs/community-guide/web.toc.html
(New page): Provide table-of-contents for new page.
* publish/docs/community-guide/web.part.html
(New page): Provide body text for new page
(Introduction): Provide brief overview of structure of web pages on
subversion site.
(web_sources): Provide instructions for accessing web sources via
https or svn.
(web_mirror): Provide instructions for creating mirror of Subversion
site with Apache.
(web_validation): Provide instructions for validating changes.
(web_patch_creation): Describe format of commit log message for
web changes.
* README
(New file): Provide link to new /docs/community-guide/web.html page.
* publish/docs/community-guide/releasing.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/issues.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/guide-nav.html
(topmenu): Add SSI variable pointing to web.html.
* publish/docs/community-guide/community-guide.html
(site-content): Add SSI variable pointing to web.html.
(Table of Contents): Add link to web.toc.html.
* publish/docs/community-guide/conventions.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/index.html
(Table of Contents): Add link to web.html.
* publish/docs/community-guide/l10n.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/mailing-lists.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/general.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/roles.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/debugging.html
(site-content): Add SSI variable pointing to web.html.
* publish/docs/community-guide/building.html
(site-content): Add SSI variable pointing to web.html.
Patch by: Gabriela Gibson <gabriela.gibson{_AT_}gmail.com>
]]]
Index: publish/docs/community-guide/debugging.html
===================================================================
--- publish/docs/community-guide/debugging.html (revision 1447927)
+++ publish/docs/community-guide/debugging.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="debugging.part.html" -->
Index: publish/docs/community-guide/releasing.html
===================================================================
--- publish/docs/community-guide/releasing.html (revision 1447927)
+++ publish/docs/community-guide/releasing.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="releasing.part.html" -->
Index: publish/docs/community-guide/l10n.html
===================================================================
--- publish/docs/community-guide/l10n.html (revision 1447927)
+++ publish/docs/community-guide/l10n.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="l10n.part.html" -->
Index: publish/docs/community-guide/web.html
===================================================================
--- publish/docs/community-guide/web.html (revision 0)
+++ publish/docs/community-guide/web.html (revision 0)
@@ -0,0 +1,34 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml";>
+<head>
+<title>Apache Subversion - Community Guide - Making Changes to the Web Site</title>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<style type="text/css">
+ @import url("/style/site.css");
+</style>
+</head>
+
+<body>
+<!--#include virtual="/site-banner.html" -->
+<!--#include virtual="/site-nav.html" -->
+<div id="site-content">
+<!--#include virtual="/site-notice.html" -->
+
+<!--#set var="GUIDE_BUILDING_PAGE" value="building.html" -->
+<!--#set var="GUIDE_CONVENTIONS_PAGE" value="conventions.html" -->
+<!--#set var="GUIDE_DEBUGGING_PAGE" value="debugging.html" -->
+<!--#set var="GUIDE_GENERAL_PAGE" value="general.html" -->
+<!--#set var="GUIDE_ISSUES_PAGE" value="issues.html" -->
+<!--#set var="GUIDE_L10N_PAGE" value="l10n.html" -->
+<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
+<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
+<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_CHANGES_PAGE" value="web.html" -->
+
+<!--#include virtual="guide-nav.html" -->
+<!--#include virtual="web.part.html" -->
+
+</div> <!-- #site-content -->
+</body>
+</html>
Index: publish/docs/community-guide/community-guide.html
===================================================================
--- publish/docs/community-guide/community-guide.html (revision 1447927)
+++ publish/docs/community-guide/community-guide.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="" -->
<!--#set var="GUIDE_ROLES_PAGE" value="" -->
+<!--#set var="GUIDE_WEB_PAGE" value="" -->
<h1>Subversion Community Guide (aka "HACKING")</h1>
@@ -53,6 +54,9 @@ first.</p>
<li><a href="#debugging">Debugging Subversion</a>
<!--#include virtual="debugging.toc.html"-->
</li>
+<li><a href="#web-site-changes">Web Site Changes</a>
+<!--#include virtual="web.toc.html"-->
+</li>
<li><a href="#mailing-lists">Mailing Lists</a>
<!--#include virtual="mailing-lists.toc.html"-->
</li>
@@ -74,6 +78,7 @@ first.</p>
<!--#include virtual="conventions.part.html"-->
<!--#include virtual="building.part.html"-->
<!--#include virtual="debugging.part.html"-->
+<!--#include virtual="web.part.html"-->
<!--#include virtual="mailing-lists.part.html"-->
<!--#include virtual="issues.part.html"-->
<!--#include virtual="releasing.part.html"-->
Index: publish/docs/community-guide/guide-nav.html
===================================================================
--- publish/docs/community-guide/guide-nav.html (revision 1447927)
+++ publish/docs/community-guide/guide-nav.html (working copy)
@@ -8,6 +8,7 @@
<li><a href="/docs/community-guide/conventions.html">Coding and Commit Conventions</a></li>
<li><a href="/docs/community-guide/building.html">Building and Testing</a></li>
<li><a href="/docs/community-guide/debugging.html">Debugging Subversion</a></li>
+<li><a href="/docs/community-guide/web.html">Web Site Changes</a></li>
<li><a href="/docs/community-guide/mailing-lists.html">Mailing Lists</a></li>
<li><a href="/docs/community-guide/issues.html">Bugs/Issues</a></li>
<li><a href="/docs/community-guide/releasing.html">Making Subversion Releases</a></li>
Index: publish/docs/community-guide/web.part.html
===================================================================
--- publish/docs/community-guide/web.part.html (revision 0)
+++ publish/docs/community-guide/web.part.html (revision 0)
@@ -0,0 +1,188 @@
+<div class="h1" id="web-site-changes">
+<h1>Web Site Changes
+ <a class="sectionlink"
+ href="<!--#echo var="GUIDE_WEB_PAGE" -->#web-site-changes"
+ title="Link to this section">¶</a>
+</h1></div> <!-- web-site-changes -->
+
+<!--#include virtual="web.toc.html" -->
+
+<div class="h2" id="web_intro">
+<h2>Introduction
+ <a class="sectionlink"
+ href="<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_intro"
+ title="Link to this section">¶ </a>
+</h2>
+
+<p>The Subversion project welcomes improvements to its web site.
+ However, the process is not as simple as clicking "Save As" in a
+ browser, editing and mailing the change. For one thing, many pages
+ are actually composed of three or more files so browsers do not save
+ a correctly rendered copy.
+</p>
+<p>
+ Because of this, if you're planning to submit substantial changes,
+ we recommend that you obtain a copy of the sources and set up a
+ testing mirror to check your changes.
+</p>
+<p>
+ Of course, for small changes, simply inspecting the patch visually
+ will often be sufficient.
+</p>
+
+</div> <!-- web_intro -->
+
+<div class="h2" id="web_sources">
+<h2>Obtaining the web site sources
+ <a class="sectionlink"
+ href="<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_sources"
+ title="Link to this section">¶ </a>
+</h2>
+
+<p>The source to the website is available from a Subversion repository.
+ To browse the sources, go to
+ <a href="https://svn.apache.org/repos/asf/subversion/site/";>
+ https://svn.apache.org/repos/asf/subversion/site/</a>
+</p>
+<p>To download a copy to <code>~/projects/svn</code>, which is the
+ location used for the rest of this page, use the following commands:
+</p>
+<pre> mkdir -p ~/projects/svn
+ cd ~/projects/svn
+ svn co https://svn.apache.org/repos/asf/subversion/site/ site</pre>
+
+<p>If you download to another location, you will need to adjust paths
+ in your web server configuration to point there.</p>
+
+</div> <!-- web_sources -->
+
+<div class="h2" id="web_mirror">
+<h2>Setting up a mirror for testing
+ <a class="sectionlink"
+ href="<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_mirror"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>The Subversion web site uses <i>Server Side Includes (SSI)</i> to
+ assemble pages within the web server. This means that to validate
+ any changes you might wish to make, you need view the relevant
+ pages through a web browser connected to a server installed on your
+ system, either
+ <a href="http://httpd.apache.org/docs/2.2/install.html";>Apache 2.2</a>
+ or
+ <a href="http://httpd.apache.org/docs/2.4/install.html";>Apache 2.4</a>.
+
+</p>
+
+<p>The following steps should provide an <i>Apache virtualhost</i>
+ that correctly renders a local copy of the Subversion web site on
+ a Unix-type system. This is likely to be located under
+ <code>/etc/apache2, /etc/httpd</code> or a similiar directory,
+ depending on your system. These instructions have been tested on
+ Apache 2.2 and Apache 2.4.</p>
+
+<ol>
+ <li>Obtain the web site sources as described in the section above.
+ <br />For the purpose of the following discussion, we will assume
+ that these are in the directory <code>/home/user/projects/svn/site</code></li>
+
+ <li>Configure an Apache server to use the <code>site/publish</code>
+ directory within the working copy mentioned above as DocumentRoot
+ for either the main server or a VirtualHost.</li>
+
+ <li>Check your Apache server includes <code>mod_include.so</code></li>
+
+ <li>Enable Server Side Includes for the relevant DocumentRoot. The
+ relevant Apache directive is:
+ <pre>Options +Include
+</pre></li>
+
+ <li>Turn on SSI parsing for html files for the relevant DocumentRoot.
+ The relevant Apache directive is:
+ <pre>AddOutputFilter INCLUDE .html
+</pre></li>
+</ol>
+
+<p>Putting it all together, an example VirtualHost configuration is:</p>
+
+<pre><VirtualHost *:8080>
+ ServerAdmin webmaster@localhost
+
+ DocumentRoot /home/user/projects/svn/site/publish
+ <Directory />
+ Options FollowSymLinks
+ ## The following line tells Apache to assemble the
+ ## pages for the Subversion site
+ AddOutputFilter INCLUDES .html
+ AllowOverride All
+ </Directory>
+ <Directory /home/user/projects/svn/site/publish/>
+ Options +Includes
+ AddOutputFilter INCLUDES .html
+ </Directory>
+
+ ErrorLog ${APACHE_LOG_DIR}/error.log
+
+ # Possible values include: debug, info, notice, warn, error, crit,
+ # alert, emerg.
+ LogLevel debug
+
+ CustomLog ${APACHE_LOG_DIR}/access.log combined
+</VirtualHost>
+</pre>
+
+<p>After restarting or reloading the server, you should see a copy of
+ the <i>Subversion community guide Web Changes</i> page if you use
+ the following link:
+
+ <a href="http://127.0.0.1:8080/docs/community-guide/<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_mirror">
+<pre>http://127.0.0.1:8080/docs/community-guide/<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_mirror</pre></a>
+</p>
+
+</div> <!-- web_mirror -->
+
+<div class="h2" id="web_validation">
+<h2>Validating your changes
+ <a class="sectionlink"
+ href="<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_validation"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>Please validate all patches which make substantial changes to the
+ web site.</p>
+
+<p>If you have set up a mirror of the website as advised on this page,
+use the command line to fetch a correctly rendered copy of the page
+you've changed with
+<pre>wget http://127.0.0.1:8080/docs/community-guide/YOUR_CHANGED_PAGE.html
+</pre>
+</p>
+<p>then upload the resulting file to a HTML validatory, for
+example, <a href="http://validator.w3.org/";>W3C validator service</a>.
+
+</div> <!-- web_validation -->
+
+<div class="h2" id="web_patch_creation">
+<h2>Creating a patch and a log message
+ <a class="sectionlink"
+ href="<!--#echo var="GUIDE_WEB_CHANGES_PAGE" -->#web_patch_creation"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>
+ When writing log messages for patches regarding the project's web pages, eg:
+</p>
+<pre>http://subversion.apache.org/docs/community-guide/some_page.html#section-name
+</pre>
+<p> list the names of files modified in the patch in the log message,
+ relative to the <code>site/</code> directory and list anchors of
+ sections added or modified like this:
+ <pre>
+ * docs/community-guide/some_page.html
+ (section-name): fixed issue xyz
+</pre>
+<p>For a full discussion of the Subversion patch requirements, please
+ follow the project
+ <a href="<!--#echo var="GUIDE_GENERAL_PAGE" -->#patches">general patch guidelines</a>
+ and
+ <a href="<!--#echo var="GUIDE_CONVENTIONS_PAGE" -->#log-messages">log message guidelines</a>.</p>
Index: publish/docs/community-guide/building.html
===================================================================
--- publish/docs/community-guide/building.html (revision 1447927)
+++ publish/docs/community-guide/building.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="building.part.html" -->
Index: publish/docs/community-guide/web.toc.html
===================================================================
--- publish/docs/community-guide/web.toc.html (revision 0)
+++ publish/docs/community-guide/web.toc.html (revision 0)
@@ -0,0 +1,18 @@
+<!--#if expr='"$DOCUMENT_NAME" = "web.html" || "$DOCUMENT_NAME" = "community-guide.html"' -->
+<ul>
+ <li><a href="#web_intro">Introduction</a></li>
+ <li><a href="#web_sources">Obtaining the web site source</a></li>
+ <li><a href="#web_mirror">Setting up a mirror for testing</a></li>
+ <li><a href="#web_validation">Validating your changes</a></li>
+ <li><a href="#web_patch_creation">Creating a patch and a log message</a></li>
+</ul>
+<!--#else -->
+<ul>
+ <li><a href="web.html#web_intro">Introduction</a></li>
+ <li><a href="web.html#web_sources">Obtaining the web site source</a></li>
+ <li><a href="web.html#web_mirror">Setting up a mirror for testing</a></li>
+ <li><a href="web.html#web_validation">Validating your changes</a></li>
+ <li><a href="web.html#web_patch_creation">Creating a patch and a log message</a></li>
+</ul>
+<!--#endif -->
+
Index: publish/docs/community-guide/conventions.html
===================================================================
--- publish/docs/community-guide/conventions.html (revision 1447927)
+++ publish/docs/community-guide/conventions.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="conventions.part.html" -->
Index: publish/docs/community-guide/index.html
===================================================================
--- publish/docs/community-guide/index.html (revision 1447927)
+++ publish/docs/community-guide/index.html (working copy)
@@ -44,6 +44,9 @@ first.</p>
<li><a href="debugging.html">Debugging Subversion</a>
<!--#include virtual="debugging.toc.html"-->
</li>
+<li><a href="web.html">Web Site Changes</a>
+<!--#include virtual="web.toc.html"-->
+</li>
<li><a href="mailing-lists.html">Mailing Lists</a>
<!--#include virtual="mailing-lists.toc.html"-->
</li>
Index: publish/docs/community-guide/issues.html
===================================================================
--- publish/docs/community-guide/issues.html (revision 1447927)
+++ publish/docs/community-guide/issues.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="issues.part.html" -->
Index: publish/docs/community-guide/mailing-lists.html
===================================================================
--- publish/docs/community-guide/mailing-lists.html (revision 1447927)
+++ publish/docs/community-guide/mailing-lists.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="mailing-lists.part.html" -->
Index: publish/docs/community-guide/general.html
===================================================================
--- publish/docs/community-guide/general.html (revision 1447927)
+++ publish/docs/community-guide/general.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="general.part.html" -->
Index: publish/docs/community-guide/roles.html
===================================================================
--- publish/docs/community-guide/roles.html (revision 1447927)
+++ publish/docs/community-guide/roles.html (working copy)
@@ -24,6 +24,7 @@
<!--#set var="GUIDE_MAILINGLISTS_PAGE" value="mailing-lists.html" -->
<!--#set var="GUIDE_RELEASING_PAGE" value="releasing.html" -->
<!--#set var="GUIDE_ROLES_PAGE" value="roles.html" -->
+<!--#set var="GUIDE_WEB_PAGE" value="web.html" -->
<!--#include virtual="guide-nav.html" -->
<!--#include virtual="roles.part.html" -->
Index: README
===================================================================
--- README (revision 0)
+++ README (revision 0)
@@ -0,0 +1,10 @@
+ The Subversion Web Site
+ =======================
+
+(Note: this file is not visible on the Subversion site)
+
+This tree contains the Subversion web site. The DocumentRoot is pointed
+at the publish/ directory.
+
+A discussion on how to set up a local mirror of the Subversion site is
+available at http://subversion.apache.org/docs/community-guide/web.html
\ No newline at end of file
