GNU Webmastering Guidelines
Information for new webmasters
If you're interested in volunteering as a GNU webmaster, please first complete the GNU webmaster quiz.
Table of contents
The rest of this document is long and detailed. Here is a table of contents of the top level items:Working as a webmaster - Using RT - Site structure - Announcements - Linking policies - Mirrors - ThankGNU/ThankCRM - Handling common requests - Working with our repositories - More README pages.
By the way, please edit and improve this document!
Working as a www.gnu.org webmaster
All active webmasters have access to the webmasters RT queue, which corresponds to the email address <firstname.lastname@example.org>. This is the primary work queue for webmasters. Please check the queue regularly, take a ticket you can handle, handle it, and reply to the message letting the sender know what has happened, and resolve the ticket. See RT guidelines below for many details.
All active webmasters should be part of the www project on savannah, so changes can be committed. Please join that if you haven't already. Most webmaster tasks are performed by checking out the CVS repository on your local machine, modifying them, and committing the result. Instructions on how to use CVS (you want the “Webpages repository”).
All active webmasters should be on the www-discuss mailing list. You should have gotten the subscription and archive information for it when you joined. If not, write chief-webmaster. Additional archives are in /com/archive/webmaster* on fencepost.
Webmasters who are planning to write a significant amount of new material for the site should provide a copyright assignment.
If you find a message to email@example.com that you don't know how to handle, it's probably best to ignore the message for a while. However, if you noticed that something has been pending for more than a few days, it is good to ask the www-discuss list: "Can someone teach me how to handle messages like this?"
As a general rule, things like this are always okay to do:
- Fix typos, misspellings, broken links, and the like (a report of broken links is available at /server/source/linc/linc-report.html The reports are separated by language code.)
- Requests from Richard Stallman <firstname.lastname@example.org>, John Sullivan <email@example.com>, or anyone else at the FSF Distribution Office.
- Requests from one of the maintainers of a software package to change something on web pages about that software package, if it does not seem to conflict with any other webmastering policies.
- Take on one of the tasks we need done for this web server. Cleaning up that task list would also be appreciated. Please inform the www-discuss list if you take a task.
Sometimes people send mails asking us to make links to different software packages. Before making such links, it's important to check the page that the link points to and make sure that it does not make any references to non-free software. When in doubt, it is best to post a summary of what you found on the page back to the webmasters list (but not to the requestor!), and ask someone else to take it from there.
We do not have links to web sites of the well-known GNU/Linux system distributions, or to the well-known BSD system distributions, because all those sites explicitly describe, and facilitate access to, various non-free programs.
Sometimes you might be tempted to rearrange the hierarchy, change the CSS formatting, layout, tagging, or other such wide-ranging things. Before doing anything like this, please consult the www-discuss list.
The following organizational rules are not rigid; they are designed to serve us and assign responsibility so that things don't fall through the cracks. Thus, the policies and escalation procedures need not be followed to the letter, but if you aren't sure what to do, it's best to follow these policies.
The GNU Webmaster Group is led by the Chief Webmaster <firstname.lastname@example.org>. You can always find out the identity of the Chief Webmaster by looking at the aliases file on the GNU mail server.
The Chief Webmaster is responsible for making sure that every message sent to webmasters <email@example.com> gets handled eventually. The Chief Webmaster isn't responsible for handling every message; just making sure that someone handles them in a timely manner. The Chief Webmaster is also responsible for training new webmasters, and doing her best to correct mishandled webmaster email, when necessary.
If it isn't clear to the webmasters how to handle a particular issue, the message should be sent to the www-discuss mailing list so that all the webmasters can learn how to handle those issues in the future.
We realize that people's lives change, and we know that you may not want to be an FSF/GNU webmaster for the rest of your life. We ask that you let us know when you want to move on: please don't simply disappear.
When you sign up to be a webmaster, you commit to a certain number of hours a week of volunteer work. If you need to drop below that level for more than a few weeks, or want to stop being a webmaster entirely, please inform <firstname.lastname@example.org> as soon as your situation changes.
Mail sent to webmasters is stored in a ticket management system called RT. This system keeps all correspondence about a given issue together, makes sure that no requests are lost, and so on. This section documents the conventions used by the GNU webmasters.
It is useful to be copied on all RT-related mail: new tickets, other webmasters' answers to tickets, and so on. That way we can all learn from each other. If you can actively help with handling RT tickets, please consider this. A number of people can set up your RT account for this, just mail www-discuss.
RT - quick guide
First and foremost: use your judgment, rather than blindly following procedures. If the action on a particular ticket seems questionable to you for any reason, email www-discuss or use the ‘Comment’ link on the ticket. That said, most tickets fall into one of a few categories, so we try to enumerate the common cases here.
- To see open tickets, visit rt.gnu.org and log in with your assigned RT username/password. (If you don't have one, email www-discuss.) There will be a link to the webmasters queue (among lots of other things) on your RT home page. Once you see the list, clicking on the subject link will open the ticket.
- If the message is spam, click the ‘Mark as Spam’ link in the top row.
- If the message is in a language you don't understand and it's not spam, or you're not sure if it's spam, click ‘Basics’, then change the Queue field to ‘web-translators’.
- If the message is just a thank-you to us, or something else that doesn't require action on our part, click ‘Resolve’.
- If the message is a simple typo or other buglet on a page we maintain, go ahead and fix it, using ‘Reply’ to tell the submitter what you did, and then ‘Resolve’ it.
- If the message is a ThankGNU or a ThankCRM see the Thank GNU procedure.
- If the message is about making a link on one of our pages, see linking procedures and information.
- If the message is about adding a graphic or a joke, be sure to get the explicit ok for it to be released under a free license—GPLv3-or-later and FDLv1.3-or-later is good. Then make a new page under /graphics resp. /fun and add it to the index page. rms' requirements for adding items to /fun is in /fun/README.
- If the message is about a mirror, see mirror procedures and information.
- If the message opened a new ticket, but is actually a follow-up to an existing ticket, use the ‘Links’ feature of RT to combine them. This happens when the original submitter cc'd the message to other recipients, and one of the other recipients sends a reply that includes us—each such reply will (unfortunately) start a new ticket.
- If the message needs to be dealt with by another group, such as sysadmin or licensing, move it to the corresponding queue or otherwise forward it. Specific directions for redirecting tickets.
RT - correspondence vs. comments
You can attach two kinds of information to a ticket: correspondence and comments.
Correspondence will be sent to the person who sent the initial report. Add correspondence when you want to get more information about the report, give the requestor more information about the work being done, let them know it's finished, and so on.
Comments are only seen by the ticket staff: the owner and people listed as AdminCCs. You can use comments to make internal notes about ticket work. For instance, if you do some work on converting an essay of RMS's to HTML, but didn't get a chance to finish yet, you could add a comment saying that you're partially done, so other webmasters know not to work on it (make sure to leave the ticket marked "open"). You should add something as a comment whenever the original requestor doesn't need to see it. Try to make as much correspondence as you can into comments, however.
Unfortunately, the methods for adding either type of correspondence are very similar, so it's easy to get them confused. Be careful.
To add correspondence, use one of the "reply" links on the ticket page, or send mail to <email@example.com> with
in the subject line, where 1234 is the ticket number.
To add comments, use one of the "comment" links on the ticket page, or send mail to <firstname.lastname@example.org> with
in the subject line, where 1234 is the ticket number.
There is no way to make other modifications except through the web interface. However, there are a couple of macro scripts hanging around for modifying email received in Emacs, or in mbox format. Please check with www-discuss for these.
RT - coordination with others
You will often need to ask other people for more information about how to handle a ticket. If we don't mind showing them a few internals about how we do things—in other words, if they're friends of the GNU project—the best way to do this is to mail them, and make that mail a comment to the ticket as well.
So, say for example that you wanted to ask rms whether a certain link on a page was permissible. You can do this by using one of the "comments" links on the ticket page, and listing the other party (in this case, <email@example.com>) as a CC:. You could also do this by sending a mail with headers like this:
To: <firstname.lastname@example.org>, <email@example.com> Subject: [gnu.org #1234] Question about link policy
1234 should be the appropriate ticket number.
The former method is more foolproof: RT will change the outgoing mail so that the only address the other party sees is RT's, and any reply will be guaranteed to go into the ticket (also as comments). The latter is fine if you're primarily doing work by e-mail, however.
Note that this won't work with other RT-handled addresses. So, if you add <firstname.lastname@example.org> to the CC field of a comment on a ticket that already exists in webmasters, nothing will come to the campaigns queue. In those situations, create a new ticket in the queue whose attention you want to get, and using the “Refers to” or similar relationship field to connect the two tickets.
RT - ticket status
Here are the possible ticket statuses in RT:
- new is for tickets which have not had work done on them yet. RT assigns new tickets this status automatically; there is no need to explicitly set it.
- open is for tickets which are being worked on. RT will automatically give a ticket this status when comments or correspondence are added; you usually won't need to change a ticket to be open manually.
- resolved is for tickets whose problems have been addressed. Do this when you complete the request outlined in the ticket, or determined it's inapplicable, or otherwise dealt with it. Until it is completely addressed, leave it open.
- deleted is for tickets which are spam (and only spam). This status is set automatically by the ‘Mark as Spam’ option in the web interface, which is the most convenient way to handle spam tickets.
- rejected and stalled should not be used.
Other considerations regarding tickets' status:
- Feel free to mark tickets as resolved liberally. If new correspondence comes in about them, they will automatically be re-opened. If it is just a random request for which there is nothing in particular to do, simply reply as needed and mark it resolved.
- However, if a ticket is important, it is best to keep it open, even when we need more information. That way, we will keep seeing it, and remember to push for the necessary information, rather than forgetting about it.
RT - ticket escalation
If you'd like to handle a request but aren't sure how to go about it, or think a request is important and may have been overlooked, leave the ticket open, and email the www-discuss list.
RT - misdirected tickets
Sometimes people send mail to webmasters which is best handled elsewhere. When this happens, you can do one of two things: redirect the ticket within RT, or forward it in regular email.
If there's an RT queue which is appropriate for the ticket, move it there. The ticket's queue can be changed under the ‘Basics’ menu item.
- Move tickets with opinions or inquiries about free software or GNU philosophy, help using specific programs, or other such non-web site-specific questions, to the info queue.
- Move bug reports and other items about the Free Software Directory to the directory queue.
- Move bug reports about fsf.org pages (broken links, typos, layout) to the resources queue.
- Move tickets that are about the actual content of fsf.org pages to the campaigns queue.
- Move tickets that are about FSF memberships to the memberships queue.
- For tickets about system problems with www.gnu.org (e.g., system down, a .symlinks file not creating the symbolic link), try to verify the problem and if it is real, move it to the sysadmin queue.
- Move tickets about a new or existing translation of a gnu.org web page to web-translators. Exception: for happy-birthday-to-gnu subtitles and other FSF campaigns pages on gnu.org, handle them ourselves.
- For tickets about Savannah, email the original message to email@example.com.
- Move tickets about licensing to the licensing queue.
- Move tickets about accounts to the accounts queue.
- Move tickets about the */allgnupkgs.html pages to the maintainers queue.
- Requests to remove messages from mailing list archives (accessible via http://mail.gnu.org should be forwarded to <firstname.lastname@example.org>.
- Anything else not related to webmastering—including questions about FSF opinions, requests for support, and the like—can be moved to the info queue.
- For tickets about the GNU libc web pages, point the OP to http://www.gnu.org/software/libc/bugs.html. That is the best way to get the glibc maintainers' attention.
- If the ticket is about the web pages for a specific GNU software package, it is best to send it in private email to the maintainers of that package (they are recorded in the Free Software Directory, or look at the file /gd/gnuorg/maintainers.bypkg on fencepost), and reply to the OP saying that you did so, resolving the ticket.
It's nice to notify a queue's watchers when a misdirected ticket is moved; RT doesn't provide automatic notification. You can do this by sending mail to QUEUENAMEemail@example.com with the original subject line. Just a terse message "Moved ticket 1234 to your queue" suffices.
If there isn't an appropriate RT queue, forward the mail to the appropriate party, and make a comment indicating that you did so (perhaps resolving it, if appropriate). It is usually best not to do this via the RT cc mechanism. Instead, forward the message in normal email.
RT - spam quarantine
The spam quarantine is a collection of mails to firstname.lastname@example.org that are caught by our spam filter, and should be checked daily for false positives.
To do this, use your RT username and password to log in to the quarantine manager. The background of the page is color coded from blue (least likely to be spam) to red (most likely to be spam). To read an email, click on its subject. If you find a false positive then click the "Send to RT" button at the top of the page. When you are satisfied that all of the emails on the index page are spam, delete them using the "Delete All Message On This Page" button at the bottom of the index page.
If the quarantine is not checked for several days, RT will synthesize a ticket in our queue. When the above is done you should resolve such a ticket. It is best not to wait around for the ticket, though, because webmasters get several hundred spams every day.
Site structure and navigation
The site is divided up into directories by topic—there's a directory for GNU project information and history, a directory for our licenses, and so on. Each of these directories has a page sharing the same name; for example, the /philosophy directory has a page, philosophy.html. This page is the main page for this section of the site, and so should provide access to all the material within that directory.
In turn, every other page in the directory should link back to this main page, to allow people to get more information about a given topic.
Links should include a full path, if possible. For example, within a specific article in the philosophy section, link to /philosophy/philosophy.html, rather than just philosophy.html. This eases maintenance of the site as things get moved around.
Some pages are dynamic and should include a link with the full hostname; a notable example is the Free Software Directory. So, we link to that with the URL <http://www.gnu.org/directory>.
Our pages make use of SSI and CSS to do a variety of things. At present, our pages should do an include of </server/banner.html>, as shown in </server/standards/boilerplate.html>. This reads /style.css, which in turn reads /combo.css (Yahoo's User Interface CSS for reset, grids, fonts and base plus /layout.css, which contains gnu.org specific CSS formatting. In addition, users of mobile devices (cellphones, music players, etc) are sent to /mini.css instead. This stylesheet is just the YUI reset and base stylesheets, as mobile devices typically have minimal need for various fonts and no need for fancy layouts.
Historical pages refer to /gnu.css which also loads the mobile CSS, as these pages are usually very basic, plain pages with little or no formatting.
A little more on Yahoo's User Interface CSS
YUI is a project of Yahoo (the search engine company) to provide a set of standard userfaces for the web. They're licensed under the modified BSD-license (3 clause), here's a quick run down of what they do:
- As all the major browsers, both free and nonfree are different, reset reverts all their specific default CSS to a very basic level, allowing the developer to provide her own styles, or use a standard library. In our case, we use base.
- Laying out pages in an attractive way can be tricky using CSS -- YUI provides a mechanism for this that is pretty attractive. Using the documentation for grids, or the interactive grids builder, the discerning developer can quickly build attractive and functional grid-based layouts, which are the cornerstone of good typographical practice without resorting to tables, which is considered a bad practice for accessibility.
- Fonts are also a mess on the web, as many gnu.org developers will tell you, we have long wrestled with the problem of how gnu.org should handle fonts. From the original 'no fonts' design, through the many interactions of Matt Lee's current GNU designs, fonts have been an often-debated problem for the site. YUI's fonts takes care of this, by use of much testing on the part of Yahoo.
- Base does the final part of the job that reset does — provides a consistent definition for all the major elements on a page. With base, headings, paragraphs and lists are consistent in their margins and padding across all browsers.
Announcements: directory links, sitemap, home page
When significant new content is added, notices should be put up to make people aware of it:
- Add a News entry (next section).
- When adding a new page, always add a link to the directory's main page. For example, if you've created a new page in the /gnu directory, add a link to it from /gnu/gnu.html.
- If a new page is sufficiently important, add a link on the home page, /home.html.
Adding news: whatsnew
News items are posted by adding a new "News" entry to the www project on Savannah.
Once that is done there is no need to do anything more. The News item will eventually appear on http://planet.gnu.org. A cron job will trigger planetrss.pl to pull new items from the RSS feed and add them to /planetfeeds.html where they are then included in home.html via an SSI Include directive. Email www-discuss if something seems to be wrong.
One of the most complex aspects of webmastering is following the linking guidelines; however, it's also a very crucial aspect of the job.
We strive to ensure that all pages we promote—all pages which are given links on our site—are friendly to the free software movement. Some pages will obviously not meet such standards; if the site flames the Free Software Foundation, or has no apparent relation to free software and surrounding issues, the link shouldn't be made. Beyond that, however, there are criteria used in determining whether or not it is appropriate to provide a link to a page from ours. They are listed below, in order of descending general importance.
- What's the context of the link?
The link's purpose on our site will play a role in determining how strongly it should be judged against the other criteria. Pages hosting GNU projects will be held to the highest standards. Pages about other free software and given high promotion—for example, included in a GNUs Flash on the main page—are a close second. Links on the philosophy page may be given more leeway in talking about proprietary software; GNU/Linux user group pages should call the system GNU/Linux almost always but are hardly checked on other criteria. Always keep this in mind when deciding how to weigh each aspect of these policies.
- Does the page promote proprietary software?
The big point made by the free software movement is that proprietary software presents an ethical dilemma: you cannot agree to such non-free terms and treat those around you as you would like to be treated. When proprietary software is promoted, people get the impression that it is okay to use it, while we are trying to convince them otherwise. As such, we avoid offering such free advertising, either directly on our site or indirectly through links.
What's tricky about this criteria is the "promotion" point: there's a difference between mentioning proprietary software and making a sales pitch for it. Indeed, the GNU project web site mentions proprietary software throughout, but never gives people the impression that its use does not present ethical problems.
There are two things to keep in mind when determining whether a reference to proprietary software promotes it, or simply mentions it. First, how much information does it offer about the software? Second, how much information is the reader likely to actually gain from this page?
Different pages provide different amounts of information about proprietary software; the more it provides, the more of a problem it poses for us. For example, some pages may link to the primary site for a proprietary software program. Others may describe its functionality in detail. Even the product name given matters; there's a difference between "Windows" and "Microsoft Windows XP Home Edition."
The subject of the reference will also play a role in determining how problematic a reference is. If the software is already very popular, it's unlikely that a basic mention of it will be news to the reader. Some examples of proprietary software which are common enough to be considered "well-known" are major operating systems (Windows, Mac OS, Sun OS, HP-UX) and primary common applications such as Office, Internet Explorer, Photoshop, Acrobat Reader, and Flash.
GNU software project pages feel the full force of this policy. Proprietary software should only be mentioned when the software provides support for it, or to compare it against the features of well-known proprietary software. For example, the following text—and not much else—would be acceptable:
w3 is a web browser for GNU Emacs, similar to Internet Explorer. It can run on all platforms GNU Emacs runs on, including GNU/Linux, proprietary Unix systems, and Windows.
Links which appear in other areas, such as the testimonials or philosophy pages, as well as links to user groups may discuss such software in greater detail, but links and other methods of encouragement to "learn more" should still be avoided.
- How does the page compare free software to open source?
Almost all pages which have links on our site should, at the very least, treat free software and open source equally. Failure to do so—whether it be by omitting free software or by implying that open source is superior—is usually unacceptable. GNU software project pages should have little mention of open source. The GNOME page provides a good example of a way to do it tactfully:-
GNOME is part of the GNU project, and is free software (sometimes referred to as open source software).
Any exceptions to this rule should be apparent from the context. For instance, user groups pages may talk in greater detail about open source; we state on the user groups page, "As with our links page, the FSF is not responsible for the content of other web sites, or how up-to-date their information is."
- How does the page treat the GNU project?
Pages which we link to should treat the GNU project well. The primary thing to look out for in this regard is whether the page calls the system GNU/Linux or just "Linux." GNU software project and user group pages should almost never, if ever, fail to do this. Again, exceptions for other pages should be apparent from context.
That said, certain parts of a page should not be considered against these criteria. For example, suppose we were to make a link to a page on a free software news site. Any advertisements or reader comments attached to the article would not be considered when determining whether it met or linking guidelines, since they're understood to be the opinion of their individual authors. Similarly, on user group pages, the content of forums and Wiki pages should not hold weight in these regards.
Finally, some sites are understood to always have exception with most of these guidelines. These sites are usually about issues which are important, but somewhat peripheral, to the free software movement. Several times we have linked to the Electronic Frontier Foundation's site, even though they encourage the use of Flash and talked exclusively about open source software. It's generally understood that since these pages are not primarily about free software, the policies do not hold full force for them.
As a final explanation (coming from RMS): Even for making links from www.gnu.org, we do not *require* that people call the system GNU/Linux or use the term "free software" rather than "open source." We do, however, require that they not promote any non-free software.
If all this seems complicated, that's because, unfortunately, it is. Don't worry; a knack for it comes with time and experience. You may mis-evaluate a few pages as you're learning to get a feel for what's acceptable and what isn't; please don't hesitate to get a second opinion from a more experienced webmaster, or someone in charge like the chief webmaster or RMS. New exceptions will always come up; keep an open mind to that possibility and be ready to handle them properly.
Links to free GNU/Linux distributions
Suggestions for links to GNU/Linux distributions should be handled like this:
- The requestors should be the primary developers of the distro, not just users. If they are users, thank them and ask them to contact the developers in case they want to be listed.
- Briefly check that the distro is a feasible candidate: they should have a clear policy of only including free software, and it should be reasonably apparent how to get the sources and what packages are included. If these things are not present, talk to the requestor about it (politely).
- If there are no glaring problems, ask the requestors to request an endorsement from the (nongnu.org) gnu-linux-libre mailing list. They should include a description of their new distro, a link to their home page, and any other useful info. Our ticket should then be resolved.
- FYI: the gnu-linux-libre list will take over from there. In essence, they will review it in detail for meeting our criteria, and if all seems good, pass it on to the FSF licensing person for final approval.
In any event, webmasters should never simply add new distros that are said to be free to our list. FSF licensing and rms must explicitly approve any additions.
Links to GNU & Free Software User Groups
Requests for links to GNU or Free Software Users Groups can be referred to the LibrePlanet website. Our ticket can then be resolved.
When we get a request to add, change, or remove a mirror of ftp.gnu.org, first ensure the mirror meets our criteria, as described on advice for mirrors; that page explains what we ask mirror volunteers to provide. If in any doubt, comment on the same ticket to ask other webmasters' opinion, or check with the webmasters mailing list and/or email@example.com before taking any action.
After confirming the mirror meets our criteria for listing, do this:
- Edit the file /prep/FTP (in CVS); it's plain text, not HTML.
makein the prep/ subdirectory.
- cvs commit both files FTP and ftp.html. In the commit log message, include the name of the mirror and its location, and the RT number if there is one.
- Update the file /gd/gnuorg/web/FTP.contacts on Fencepost, keeping the pattern as explained at the beginning of the file.
- See next entry about the status of mirrors.
Checking the Status of Mirrors
Mirrors are useful as long as they are kept up-to-date. Outdated mirrors can even be harmful, since downloading old versions of software may involve security risks for users. Checking the status of mirrors is therefore an essential part of the process of adding/modifying mirrors.
A mirmon page tracker (maintained by savannah) shows how up-to-date each mirror is. When a mirror has gotten more than a few days out of date, it is necessary to contact its maintainers and let them know about the problem so that they can fix it. For examples on how to do this, search the RT system for tickets with subjects containing “[Mirror Status]”.
If a mirror needs to be removed, please check to see if it is referenced on /server/mirror.html and remove that entry as well.
The address http://ftpmirror.gnu.org/PKG (also maintained by savannah) multiplexes between the mirrors, trying to choose one that is nearby and up to date.
When we get a request to add, change, or remove a nongnu savannah mirror, email firstname.lastname@example.org with the information. The reason to use -private is to avoid the contact address from becoming public. If the email address of a mirror admin is not involved or there are no other privacy issues, it's better to use email@example.com.
We no longer recommend or list mirrors of www.gnu.org.
Mirror contact information
When we get a request relating to a mirror, please check the file /gd/gnuorg/web/FTP.contacts on Fencepost and add contact information if it's not there already, or update it, if necessary. We lack information for many older mirrors, or the data we have is not up to date.
Ibiblio URL changes
If we are told or determine that there is a change in the rsync URL or the advertised source mirror URLs for ibiblio, all mirror maintainers should be informed. This requires hand-assembling a list of addresses from the FTP.contacts file based on the current mirror list.
- For a corporation, confirm that they are not a current patron. Occasionally, a patron may accidentally donate via the standard FSF donation form.
- For an individual, add it to the appropriate /thankgnus/YYYYsupporters.html file in the correct place with a commit message such as "Add John Doe to YYYY >= 500$ ThankGNU list (RT #1234)" and comment the ticket with something simple like "Done".
- Mention in a RT comment whether you added an entry or not. The script sending out the messages has bugs. The occasional case of a person donating the same amount twice is handled by FSF staff.
- Finally, move the ticket into the 'campaigns' queue.
Things to watch out for:
- Do not quote the dollar amount in the commit message or anywhere else, just the name, ticket number and category.
- Do not ‘Reply’ to sysadmin on these messages; they are automatically generated.
- Do not post a ThankGNU for Google Matching Gifts.
Handling common requests
There are a number of requests which recur frequently. This section documents guidelines for handling these types of requests.
Those requests which are extremely straightforward—for example, fixing typographical errors, or problems in HTML formatting—are not documented here. Only requests which may require non-obvious action are listed.
Fixing dead links
Please check the broken link report regularly and handle them. If a link has gone bad because a page has moved, try to find its replacement. If you are successful, re-check the page to ensure that it meets our linking criteria, and if so, add it. If you do not find a replacement, remove the link—if it's central to the page, you may need to make a note explaining that the resource is no longer available. If the page no longer meets our linking criteria, you'll have to make a judgment call, and weigh the value of the link against its problems'; you may want to mail the person who wrote the page with the link or www-discuss to get a second opinion.
If you do remove a link from a page that we don't maintain—for instance, the page for a piece of software which is kept up-to-date by the maintainer—please notify them of the problem and what you did to fix it.
We'll sometimes be asked to add links to the page; most often, this will come from RMS, asking us to add a page to the Other People's Views section of the philosophy page or as part of a GNUs Flash to the front page.
If the person requesting the link is a friend of the GNU project, check the page against our linking criteria, and if it passes, add the link as requested. If it does not meet our linking criteria, send mail back to the requestor, saying so and outlining in detail what the problem(s) with it are.
If the suggestion is coming from someone outside the GNU project, check the page against our linking criteria, and if it passes, forward the suggestion to the appropriate party. If the link would be part of the main GNU site, that would be someone who can speak for the GNU project, such as RMS. If the link would be part of a software page, direct it to the person responsible for the program's site—if no other contact is given, that would be the maintainers themselves. If you're told that adding the link is acceptable, do so. If the link fails to meet the linking criteria, thank the original requestor for their suggestion and explain that we don't feel the link is most appropriate for our site.
Adding new articles
Occasionally, RMS will mail an article, usually in plain text, to webmasters and ask that they put it on the site. The text needs to be converted to the HTML and put into our standard boilerplate; you can use /boilerplate.html to provide a template for the header and footer, or base your page from another article. There are some things which you should look out for when doing the conversion:
- When they exist, preserve double spaces after sentence breaks.
- Ensure that the article's title is put in both the <title> tag and in the <h2> text at the top of the page.
- Put the author of the article in the page's header as well.
- Provide a link back to the directory's main page. If it is a speech or an interview, briefly state the topic.
- New pages (and existing pages) should have a timestamp at the bottom. See the boilerplate file for the precise location and format.
Writing and reviewing items for /proprietary
Web pages for official GNU software
GNU software maintainers usually gain CVS write access to their /software subdirectory by registering their project with Savannah. (In the past, they provided webmasters with pages for us to install on the site, but that is no longer the best procedure.)
In general, package maintainers are responsible for their own content, and thus webmasters should not make changes to package-specific web pages unless we're asked to. We do have the technical permission to check out any GNU (or non-GNU) web repository from savannah and commit changes, if a maintainer asks us to, or confirms a particular change.
Translations: Adding and deleting
Adding: Occasionally, someone will send us a translation of a single page. Move these tickets to the web-translators queue.
Deleting: Here and there you might find a translated page which is actually a copy of the original page (i.e., not a translation at all), or translations which seem like they should not exist in their current form for whatever reason. In such a case the best thing to do is to ask the relevant translation team for the reasons they put the page there (please, make sure to CC firstname.lastname@example.org on such cases). They might have reasons you are not aware of. In case you do not get within two weeks a satisfactory reason for the page to be left alone, you can handle it as you see fit.
Requests for permission to use an image
When someone emails requesting permission to use an image from the Art section of the site, the first thing to do is to check the web page that the image is on. Most of the images have a clear license on the page with them. If the permission being requested are reasonable but are incompatible with that license, forward the ticket to the licensing queue. Otherwise draw their attention to the license.
If the web page with the image on does not have a clear license and the request is a clear-cut "yes" or "no", respond to the requestor directly and explain the decision with reference to GNU policy. For more difficult cases forward to licensing.
When considering a request, err on the side of caution. If the use of an image isn't something we'd link to, for example, then it isn't something we should give permission for. Feel free to discuss any requests with www-discuss before responding to them.
Handling press releases
Occasionally, the webmasters are asked to handle press releases. These are in the /press directory. You should always make both a text and HTML version, and follow the format used for other press releases. (Some do have PDF and Postscript, but webmasters need not worry about that at the moment).
Currently, it is often johns who handles the text version of a press release. He will normally commit the ASCII version, and then tell webmasters to do the "rest" or "DTRT" (do the right thing) with it. Sometimes the file will be emailed to webmasters instead. You will also be given a date and time when the press release should be up.
At present, always check with johns before posting any press releases sent in by other parties, and note that johns will always GPG-sign his messages about press releases.
To handle one of these requests, here is what you should do:
- Make an HTML version of the ASCII file, following the
format used for other press releases. Be sure to change the
Descriptionto reflect the new press release. Also, make any URLs in the press release into actual links.
- Make an entry at the top of the list on /press/press.html for the press release.
- Add an entry to the whatsnew page.
- Make the whatsnew entry a GNUs Flash (add an asterisk to the entry) unless the request to post the release specifically says not to put a note there.
- A release date and time "window" will be included in the request to
post it. The
cvs commitshould only be done in that window. If you won't be able to do it then, use the
makepatchcommand (it's in the makepatch package of Debian) to send a patch back to johns, and put URGENT in the subject line.
- The final step is submitting it as a story to as many news sites as possible (linuxtoday.com, slashdot.org, and newsforge.com should definitely be done). This can be done later in the same day as when the release goes up, but should also be done the same day.
Working with webmaster-related repositories
Main www repository:To make an initial checkout, set the environment variable CVS_RSH=ssh, and run
cvs -d <username>@cvs.savannah.gnu.org:/web/www co www
You should end up with a directory www with the CVS checkout of our web site.
CVS cheatsheet: use cvs add foo to add a file or directory. Use cvs update -P foo before you commit a file, and cvs commit foo to perform the commit. Changes (except to .symlinks files) should be instantly visible on www.gnu.org. For further details on cvs, such as reverting to a previous version, or see diff output of particular changes, see the CVS documentation.
Without being excessively verbose, log messages should describe as clearly as possible the nature of the commit including any related ticket numbers from RT to allow future historians to understand why your changes were made.
Whenever possible, changes to multiple files that share the same log message should be bundled in one commit. Do not bundle multiple unrelated changes in one commit.
audio-video repository: Use audio-video instead of www and you will get the repository corresponding to audio-video.gnu.org. Discuss any changes to audio-video with email@example.com.
The task of adding material to this repository is currently being handled by the GNU and FSF audio and video group in Savannah, so when we get a request to add a video or audio file, we should either submit a new task there or forward the request to their mailing list at <firstname.lastname@example.org>.
Other packages: Many software packages have their own projects on Savannah and hence their own web repository corresponding to their www/software/fooproject directory. If the maintainer needs your help with one of their web pages, you can get to it like this:
cvs -d <username>@cvs.savannah.gnu.org:/web/fooproject co fooproject
Do not edit the web pages for software projects unless the maintainer says ok. At the very least, inform them if you make a change.
A description of scripts and software used on www.gnu.org is available. Please read it before writing any scripts, and also update it as needed.
Since CVS is not able to handle symbolic links directly, a separate mechanism has been implemented to allow webmasters to maintain symbolic links, as follows. (Actual symbolic links are no longer created on www.gnu.org; mod_rewrite rules are used instead. But we'll keep this discussion talking about symlinks since it is easier to understand that way.)
Being a symlink means that relative links from the linked page may break when the symlink jumps to a different directory.
Special files, named .symlinks, can be committed to the CVS tree that are interpreted as specifications to build symbolic links. On commit, the current directory is searched recursively for .symlinks files. Only directories containing a .symlinks file are handled.
Each symbolic link specification from the .symlinks file is honored, i.e., the symbolic link is created if it does not exist yet. If a symbolic link is found in the directory and is not listed in the .symlinks file, it is removed.
As a special case, if a page with the directory's name exists, and index.html does not exist, a link will be made from index.html to the main page.
The .symlinks files obey the "ln -s" format, as described below:
Lines starting with a sharp sign ("#") are ignored.
Lines that do not contain two strings separated by white space are silently ignored.
Symbolic links that point outside the web site document root are ignored.
Here is an example of a .symlinks file:
# Make a link named l.html to a target t.html. # Strictly equivalent to ln -s t.html l.html: t.html l.html
On each line the first file name must be a relative path name to an existing file. The file designated by this path must not be outside the document root. The second file name may not contain any slash; it is the name of the symbolic link to be created in the present directory.
As a special case, if a file name ends in “.html”, single
line defines links to all possible translations that follow our naming
conventions. As a side effect, this makes it impossible to use
symlinks to redirect to and from HTML files whose names look like
translations, that is,
page.LL-CC.html, where LL and CC are two-letter
codes. When you need such redirections, use the htaccess mechanism.
These days, the .symlinks handling happens on www.gnu.org via a cron job that runs twice an hour. Webmasters do not have access to it.
.htaccess and redirections
To browsers, the symbolic links in the previous section are indistinguishable from the actual file. You may want an actual redirection in some cases. You can do this either in the top-level control file .htaccess, or by using something like this as the file to be redirected:
<meta http-equiv="refresh" content="0; url=http://www.gnu.org/target">
The system administrators for GNU change from time to time. Please email the sysadmin list (email@example.com) rather than an individual, unless you have a specific reason to do so.
More README pages
- The FSF HTML Style Sheet
- GNU Accessibility Statement
- Guide to translating GNU web pages into other languages
- Guidelines for Web Page Creation at www.gnu.org
- Administration Guide to Savannah, the SourceForge clone dedicated to the GNU project.
- Here is the help (14k characters) we need with our web server
- README for the gnumaint directory in the womb Savannah group. (Those files are used by GNU maintainer administrators to update the */allgnupkgs.html files here in www.)
- Tips for webmasters to make translators' job easier.