360 lines
14 KiB
Plaintext
360 lines
14 KiB
Plaintext
$Id: webmaster-HOWTO.txt,v 1.6 2001-08-27 22:40:52 olberger Exp $
|
|
|
|
This document is a HOWTO for any volunteer interested in acting as a
|
|
webmaster for the FSF Europe website (www.fsfeurope.org).
|
|
|
|
Author : Olivier Berger <oberger@april.org>
|
|
|
|
Remarks by others between (( and ))
|
|
|
|
|
|
Topics covered :
|
|
----------------
|
|
|
|
* Configuration Management
|
|
* Publication mechanisms
|
|
|
|
Configuration Management :
|
|
--------------------------
|
|
|
|
The website is modified by various volunteers and can potentially
|
|
become very large.
|
|
|
|
We must ensure integrity of the site (visitors always see a correct
|
|
website, without dead links, for instance), and capacity to undergo
|
|
major modifications, that may require some synchronisation by various
|
|
individuals.
|
|
|
|
Thus, the web site will be available in two versions : - the main site
|
|
displayed at www.fsfeurope.org - the beta site displayed at
|
|
beta.fsfeurope.org
|
|
|
|
Both versions are constructed out of the CVS repository (hosted by
|
|
savannah.gnu.org).
|
|
|
|
CVS can maintain different "branches" in one repository that can
|
|
develop independently from each other and merged again later.
|
|
|
|
This allows having both versions of the site (www and beta) in the
|
|
same CVS repository and in the same files, but corresponding to
|
|
different branches. Modifications can be made available on whichever
|
|
branch is appropriate.
|
|
|
|
If modifications made on one version of the site must be reproduced on
|
|
the other, CVS merge operations can be done.
|
|
|
|
But attention : the merging process can be quite painfull sometimes,
|
|
and it is most important to carefully plan on which branch you want to
|
|
work, depending on the amount of modifications / type of modifications
|
|
you will later need to merge on other branches.
|
|
|
|
There are two solutions for handling the beta and production servers
|
|
on two different branches :
|
|
|
|
* take a standard up-to-date repository of the FSF Europe CVS and
|
|
create a beta branch to start at the current state.
|
|
|
|
* have the beta version on the main trunk, identify stable states by
|
|
tags, and create branches from this stable state, which will be
|
|
published as the production website.
|
|
|
|
The second solution should be used. Note that it is more similar to
|
|
the one used (most commonly I think) on development projects :
|
|
|
|
* the main branch (HEAD) is the one which contains the modifications
|
|
which consist of the most difficult things to do. Then you don't
|
|
have to merge those heavy modification on other branches ;) One less
|
|
problem.
|
|
|
|
* other branches are created to reflect only "patches" applied to
|
|
stable versions (this implies that stable versions should be
|
|
determined ;). These slighter modifications are easier to track and
|
|
merge to the other (HEAD or other) branches.
|
|
|
|
The officiel/public production version (i.e. www.fsfeurope.org) is
|
|
then the result of publishing a branch, and beta.fsfeurope.org
|
|
consists of the HEAD branch.
|
|
|
|
When modifications made on the HEAD/beta are declared good for
|
|
publication (after some review process), then, the checked-out copy of
|
|
the official/public should be directed to another branch.
|
|
|
|
I propose the following naming scheme for CVS tags :
|
|
|
|
- stable version of the www.fsfeurope.org site :
|
|
* S_FSFE_isodate[_patch_numbers] for stable versions (root of patch
|
|
branch, or tagged patched versions) - examples : S_FSFE_20010825,
|
|
S_FSFE_20010825_3
|
|
|
|
* BS_FSFE_isodate for branch containing patches of the stable
|
|
version S_FSFE_isodate - example : BS_FSFE_20010825
|
|
Should be applied exactly to the stable version which is its
|
|
root. Thus both commands should be issued at the same time :
|
|
cvs tag S_FSFE_isodate
|
|
cvs tag -r S_FSFE_isodate -b BS_FSFE_isodate
|
|
|
|
- beta version of the www.fsfeurope.org (will be on beta.fsfeurope.org) :
|
|
no need of tags, since it is on the main trunk... use cvs update -A
|
|
|
|
(( Remarks greve 20010827
|
|
One of the goals is to get a consistent layout/design between
|
|
the main site and the chapters. Why would anyone want to split
|
|
off a revision for a chapter? Maybe this is a little misleading?
|
|
|
|
Oberger 20010827 :
|
|
Good care should be taken to have the stable version identical for
|
|
all sites : main and the chapter's. But in the case certain
|
|
chapter's specific projects are too difficult to convert to new
|
|
version, or some local translations are late, it should be best to
|
|
have the main site become stable as soon as possible, putting a new
|
|
stable tag on the main trunk, while the local chapters keep n-1
|
|
stable version... Then the main site can (and must) evolve on the
|
|
fastest pace while local chapters being allowed to get more delays
|
|
in adapting to the new elements. ))
|
|
|
|
- stable version of the france.fsfeurope.org site :
|
|
|
|
* S_FSFEFR_isodate, etc.
|
|
|
|
* BS_FSFEFR_isodate, and so on...
|
|
|
|
- beta version of the france.fsfeurope.org (will be on
|
|
beta.fsfeurope.org/fr/) : no need of tags, as for the beta of
|
|
www.fsfeurope.org.
|
|
|
|
Example :
|
|
|
|
|
|
1.4 S_FSFEFR_20010903, BS_FSFEFR_20010903
|
|
|
|
|
| 1.2.2.4 S_FSFEFR_20010825_1
|
|
1.3 |
|
|
| 1.2.2.3
|
|
| |
|
|
| |
|
|
| 1.2.2.2
|
|
| |
|
|
| 1.2.2.1
|
|
| / BS_FSFEFR_20010825
|
|
| /
|
|
1.2 S_FSFEFR_20010825
|
|
|
|
|
1.1
|
|
|
|
toto.xhtml
|
|
|
|
In this example, the file toto.xhtml was patched several times (typo
|
|
for instance) coming from the 1.2 revision stabilized on 20010825,
|
|
while it was modified in parallel on the main trunk in the beta
|
|
version.
|
|
|
|
|
|
|
|
|
|
Publication mechanism :
|
|
-----------------------
|
|
|
|
The configuration management section describes the principles of using
|
|
CVS for storing the versions of the website. But this only applies to
|
|
sources of the pages (XHTML mostly), which must then be compiled into
|
|
HTML in the right place for publication.
|
|
|
|
Updates of the sites are made visible by updating the checked-out
|
|
files (from the CVS), then recompiling pages.
|
|
|
|
This can be done with "make sync" launched on the webmaster's side
|
|
(which then launches the update remotely with ssh), or at times
|
|
specified by crontabs on the server.
|
|
|
|
All this is described in the
|
|
http://france.fsfeurope.org/server/server.en.html#Web URL. Feel free
|
|
to point to insufficient documentation (or improve it directly by
|
|
committing ;).
|
|
|
|
Once a checked-out image of the CVS (of a certain branch) is in a
|
|
directory, it will continue to contain updates to that branch, so
|
|
configuration of the branch checked-out for a certain site will only
|
|
have to be made once, and could be changed almost on the fly if
|
|
necessary (returning to a stable tagged version, for instance).
|
|
|
|
|
|
Example of a session with beta and stable versions :
|
|
----------------------------------------------------
|
|
|
|
This is meant as demonstrating how to handle both stable and beta
|
|
versions in parallel.
|
|
|
|
|
|
(( Remarks greve 20010827
|
|
I have to admit that I don't entirely understand the following
|
|
paragraph.
|
|
|
|
Oberger 20010827 :
|
|
At the moment of writing, AFAIK, the "beta" and "www" virtual hosts
|
|
direct to the same directory. That's why it's impossible to take to
|
|
different checked-out branches for these two sites... Than I have
|
|
to use some temporary directory as described below. Is it clearer ? ))
|
|
|
|
For this demonstration, we'll use the following directory of the CVS
|
|
repository : /fsfe/server/testbeta. Files will be put in this
|
|
directory and modified in certain brances only. As no beta website is
|
|
available as http://beta.fsfeurope.org with its files in a different
|
|
space from the stable site, we'll use two sets of directories.
|
|
|
|
- The stable version of this directory is checked-out on
|
|
http://www.fsfeurope.org/server/testbeta/, viewing a specific branch
|
|
specified in the Makefile of /fsfe/Makefile (variable STABLEBRANCH -
|
|
see "sync:" rule for details of cvs commands in the Makefile).
|
|
|
|
- The beta version of this directory is checked-out on
|
|
http://www.fsfeurope.org/server/test/fsfe/server/testbeta/, viewing
|
|
the "HEAD" branch (main trunk) (see "sync:" rule for details of cvs
|
|
commands in the Makefile).
|
|
|
|
We'll discuss here a scenario demonstrating how CVS can be used to
|
|
manage both versions. Feel free to experiment with this sandbox to
|
|
further this scenario.
|
|
|
|
(( Remarks greve 20010827
|
|
Does this mean people are free to change things there without
|
|
risking to break stuff?
|
|
|
|
Oberger 20010827 :
|
|
Yep. One could commit as he wants into fsfe/server/testbeta making
|
|
experimentation between branches... but be carefull anyway not to
|
|
apply cvs commands to the whole repository, nor change something on
|
|
the server in the checkout directories under the "www"
|
|
account... but no one's expected to work there, isn't it ? : every
|
|
modifications are made on the client's side, and the only thing to
|
|
do is "make sync" to update the online version. ))
|
|
|
|
We won't detail CVS commands. The use of some graphical tool to
|
|
represent CVS revisions might help (I personnaly recommand tkcvs). You
|
|
may see the resulting tree in savannah's viewcvs tool :
|
|
http://savannah.gnu.org/cgi-bin/viewcvs/fsfe/server/testbeta/?cvsroot=www.gnu.org
|
|
|
|
1) isolating a stable branch from the beta/main trunk evolution :
|
|
|
|
Initialy, we have version 1.1 of toto file (only file in this
|
|
directory, contains nothing, btw), in the main trunk.
|
|
|
|
We tag it (and, btw, the rest of the directory... transpose to the
|
|
whole of the repository) as a stable version :
|
|
cvs tag S_20010825
|
|
cvs tag -r S_20010825 -b BS_20010825
|
|
|
|
Then, we add a new file (titi) in order to make it appear on the
|
|
stable site, on the BS_20010825 branch :
|
|
cvs update -r BS_20010825
|
|
touch titi
|
|
cvs add titi
|
|
|
|
We edit both files and commit modifications, which are made on branch
|
|
BS_20010825, since we got a sticky tag doing the "cvs update -r
|
|
BS_20010825" : every modifications made after such an update happen on
|
|
the branch.
|
|
|
|
This state is tagged as DEMO_STABLE_1 in the repository, if you wish
|
|
to see it.
|
|
|
|
|
|
Now, we switch to the main trunk to prepare something for the beta
|
|
version of the site :
|
|
cvs update -A
|
|
|
|
The file titi, which was added on the stable version only now
|
|
disappears. That's where we have to be carefull : too many additions
|
|
on the stable branch instead of additions on the beta will make it
|
|
harder to keep synchronized... creating a news stable version before
|
|
out of the beta might be better...
|
|
|
|
We now want to add a new file (tutu) on the beta version
|
|
touch tutu
|
|
cvs add tutu
|
|
|
|
We make modifications on tutu and toto, then commit it. The files are
|
|
modified on the main trunk only. Note that tis state was tagged
|
|
DEMO_BETA_1.
|
|
|
|
Now, the Makefile must contain the branch tag name of the stable
|
|
version if we want things to appear online when applying the sync:
|
|
rule...
|
|
|
|
We can make sync and check :
|
|
http://www.fsfeurope.org/server/test/fsfe/server/testbeta/ contains
|
|
only the beta : toto and tutu, and
|
|
http://www.fsfeurope.org/server/testbeta/ contains only the stable
|
|
version : toto and titi.
|
|
|
|
|
|
Now if we want to reflect in te beta branch, the addition of titi,
|
|
similar to its version on the stable branch we have to issue a :
|
|
cvs update -j BS_20010825 titi.
|
|
|
|
Titi appears on the main trunk.
|
|
We can commit it now.
|
|
|
|
Adding files in both versions
|
|
-----------------------------
|
|
|
|
(( Remarks greve 20010827
|
|
I have to admit this section is a little unclear to me.
|
|
|
|
Oberger 20010827 :
|
|
Well, you have to consider what happens quite frequently : files
|
|
are added to directories, when there is need to publish new pages
|
|
on the site. Either this corresponds to a modification in the beta
|
|
version, either it's something done on the stable version (adding
|
|
pieces of news, articles, which don't impact the whole structure,
|
|
don't need to be reviewed, and then can directly be added to the
|
|
stable version, right ?). In the latter case, every modification
|
|
made on the stable version has to be ported to the beta site also,
|
|
if we don't want to loose some information when going from one
|
|
stable version to the next. cvs update -j make the job for you,
|
|
"merging" from the stable branch to the beta, as I described it
|
|
above... but another solution exists, which permits to do without
|
|
any merge... but requires working first on the beta instead of on
|
|
the stable version... But actually, this is what we may prefer to
|
|
do : add on beta (main trunk), and make it also available to the
|
|
stable : just put a branch tag on it... cool ;). Am I clearer now ?
|
|
Maybe you have to experiment with CVS to understand that, cause it
|
|
would be pretty long to explain in more details ? ))
|
|
|
|
One problem with this strategy is that certain parts of the website
|
|
may require frequent modifications on the stable version (for instance
|
|
if a news section requires minimum review before publication and does
|
|
not require changes between beta and stable). Instead of having
|
|
separate revisions on two branches, but identical, and using the
|
|
merging mechanism with update -j as described above we may prefer
|
|
adding the file on both branches at the same time.
|
|
|
|
Another alternative for adding a file both on beta and stable
|
|
versions, is the one explained here : the file is added first on the
|
|
beta version (main trunk), and then the branch tag of the stable
|
|
version is added on that file. The same revision then appears on both
|
|
versions.
|
|
|
|
If the file is to evolve and its modifications have to appear on both
|
|
sites identical, then moving the branch tag to the new revision on the
|
|
main trunk would be preferable.
|
|
|
|
|
|
Recommandations for webmasters :
|
|
--------------------------------
|
|
|
|
In order to work in good intelligence and avoid unnecessary hassle
|
|
when using such branch mechanisms, webmasters should be fairly
|
|
familiar with CVS use, and be particularly cautious with the following
|
|
points :
|
|
|
|
- checking in which branch they are working before any cvs add or cvs
|
|
commit operation, in order not to commit to a branch if instead the
|
|
file had to be added/modified on the main trunk
|
|
|
|
- use a tool allowing them to understand in a graphical
|
|
representation, the revision tree, so that necessary merges can be
|
|
identified.
|
|
|
|
- document merges between branches (assistance of a tool may be
|
|
useful to track merges)
|