Getting started with comments.apache.org

  1. Introduction
  2. Features
  3. The system in action
  4. Setting up your project to use comments.a.o
  5. Moderating comments
  6. Using the digests view
  7. Non-committer moderators
  8. Content allowed in comments
  9. Subscribing to comments
  10. Mailing list notifications
  11. IRC notifications
  12. Verified users
  13. Getting additional help
  14. Styling comments
  15. Someone is spamming our site, what do we do?
  16. Help! I deleted my site by accident, what do I do?
  17. Can I use this system on a non-apache.org site?
  18. Comments

Introduction

The Apache Comments System adds a commenting system to all projects that wish to make use of it. It plugs into any HTML page, and allows readers to read and write comments on a page.

The system is tied into the LDAP authentication system, giving all Apache committers the right to moderate any of the sites using the comment system, thereby pooling our resources in helping out all the projects that make use of comments on their web sites.

Features

Among many other wonderful things, the system supports the following:

The system in action

Here are some projects that already use comments.a.o. Check out their sites to see it in action, or click here to go to the comments.a.o testing ground (which may or may not be littered with comments)

Setting up your project to use comments.a.o

If you have ANY questions about this part, please feel free to ask for help - it doesn't cost you anything.

Setting up your site to use the comments system is fast and easy, and is done in three steps:

  1. The VP of your project contacts the comments.a.o admins (fx. on #asfinfra or through a JIRA ticket) and is granted project admin rights.
  2. The site is created in the comments.a.o control panel.
  3. A HTML snippet is inserted on your web site. This snippet is retrieved via the control panel.

CMS users: As explained when you retrieve the HTML snippet for your project, the variable {{path}} (preferably) needs to be set to the absolute URL of the page that a user is viewing. If you use the ASF CMS system, this can be accomplished by using the following: http://[project].apache.org{{path}}. If your project is, for example, the Apache HTTP Server, then {{path}} should be replaced by the full URL: http://httpd.apache.org{{path}}.

The following HTML snippet would work with the httpd project's CMS system:

<div id="comments_thread"></div>
<script type="text/javascript" 
  src="https://comments.apache.org/show_comments.lua?site=httpd&amp;page=http://httpd.apache.org{{path}}" async="true">
</script>
<noscript>
<iframe width="100%" height="500" src="https://comments.apache.org/iframe.lua?site=httpd&amp;page=http://httpd.apache.org{{path}}">
</iframe>
</noscript>
Setting {{path}} is not vital - you can leave it blank and let the system figure it out, as shown below:
<div id="comments_thread"></div>
<script type="text/javascript" 
  src="https://comments.apache.org/show_comments.lua?site=httpd" async="true">
</script>
<noscript>
<iframe width="100%" height="500" src="https://comments.apache.org/iframe.lua?site=httpd">
</iframe>
</noscript>
However, if the page ID is not set, it can theoretically cause some irregularities with browsers where the Referer header is not sent, so you are advised to set it if possible.

Moderating comments

Note: To be able to moderate, you will need to allow cookies to be set for comments.apache.org (this is done using a secure https cookie).

Moderating comments should be rather intuitive. When visiting a page with comments enabled, you will - if you are not already logged on - have the option to log on and start moderating. Logging on will take you back to the comment you were viewing. Once logged on, all comments will have an extra set of actions next to the poster's name, such as Delete, Approve, Sticky and so on:

To get a better view of what's going on with comments on your site, you can visit the control panel by clicking the Moderate link when viewing comments. This will take you to your site's dashbord in the comment system. From here, you can review the latest comments, see the most active commenters, and delete/approve comments, both one at a time, or you can choose to view and manage all posts made by a specific commenter, fx delete all comment made by a spammer, or taking it one step further and banning him/her.

Using the digests view

The digest view is a searchable/browsable version of the dashboard, allowing you to find posts that are fx. from a certain period in time, contain a specific keyword, or are marked in a specific way. It also allows you to perform batch operations on multiple comments at once, such as deleting comments, marking them with a specific flag, or undeleting them. Furthermore, site administrators can use the digest view to purge comments completely from the system.

To access the digest view, simply select a site to moderate from the landing page on comments.apache.org and then click on the 'Digests' link in the top menu.

Non-committer moderators

People that are not Apache committers are generally not allowed to moderate sites. However, it is possible for them to gain moderation rights to a single Apache project. To do this, follow these steps:

  1. The non-committer register an account with the comments.a.o system (preferably through the "log in" link on a comments page)
  2. Your project admin or whoever shouts the loudest asks infra to grant him/her moderation rights (userlevel 3)
  3. Your project admin clicks on the access list in the site chooser and adds the username to the list of noncom moderators
  4. Your new non-com friend now has moderation rights for your site!

Content allowed in comments

HTML is not allowed in comments, and will just display as raw source code if attempted. Links that do not point to an Apache site (*.apache.org) will need approval before the comment is visible to regular visitors. These comments will usually appear with a red background (unless styled otherwise).

Subscribing to comments

Moderators can subscribe to comments for a particular site (or several). To do this, go to the control panel, select the site you want to subscribe to, and click on Subscribe in the site's dashboard. You will now receive email notifications whenever someone posts a new comment on that site. To unsubscribe, click on the unsubscribe link in the dashboard.

Mailing list notifications

You can set new comments on your site to be passed on to a mailing list in the configuration section of your site. Please note that the system cannot subscibe to mailing lists itself, so you'll have to allow daemon@urd.zones.apache.org to send emails to your list.

IRC notifications

Apache channels on the Freenode IRC network can have ASFBot deliver notifications about new comments on a site. Contact infra (on #asfinfra or file a JIRA ticket) to have notifications shown in your IRC channel.

Verified users

Besides committers, who are automatically verified when they log on using their credentials, it is possible for regular users to become verified by the system. The verification system works much like the verified account system on Twitter. Verified users gain the Apache feather next to their name, and may post comments with links in them without requiring approval before the comments are shown. This feature can be used by projects to gradually allow people to become an active part of the community and respond on behalf of projects without having to give them commit access right away. Being a verified user in itself does not give a user moderating rights, you will still need to be a committer (or earn your keep) in order to moderate.

To make a user verified, please contact a comments.a.o administrator and let them know which username and email, the user signed up with.

Getting additional help

If you require additional help with your comments system, you can contact any of the comments.a.o admins through the standard infra channels, such as #asfinfra on the Freenode IRC network, filing a JIRA ticket, writing to infrastruture@a.o and so on.

Styling comments

The comment section comes with a default style, that should suit most sites. If you wish to use another style, whether it be one of the predefined styles or an external stylesheet, you can do so by adding &style=[style] to the .lua scripts' query strings. Currently, the predefined styles are: default(leave out the style argument for this), basic and simplistic.

To use either the basic or the simplistic style, you would append it to the URLs like so:
[...] src="https://comments.apache.org/show_comments.lua?site=httpd&style=simplistic&page=[...].

If you wish to use an external stylesheet, you can specify so by adding the full URL of your external stylesheet as an argument. For instance, the full HTML snippet of an OpenOffice site using the comment system with their own stylesheet would look like this:

<div id="comments_thread"></div>
<script type="text/javascript" 
 src="https://comments.apache.org/show_comments.lua?site=openoffice&amp;style=http://www.openoffice.org/foo.css&amp;page=http://www.openoffice.org{{path}}"
    async="true">
</script>
<noscript>
<iframe width="100%" height="500" 
 src="https://comments.apache.org/iframe.lua?site=openoffice&amp;style=http://www.openoffice.org/foo.css&amp;page=http://www.openoffice.org{{path}}">
</iframe>
</noscript>

Someone is spamming our site, what do we do?

Follow these steps:

  1. If the spam is massive and ongoing:
    1. Visit the landing page and select the "Configuration" link next to your site.
    2. Check the "Disable posting of new comments" box.
    3. Optionally, check the "Disable showing of comments" to prevent the spam from showing, while you manage it.
    4. Click on "Submit request" to save the settings. Your site is now guarded against new spam while you fix it.
  2. Go to the dashboard for your site (click on the site name on the landing page).
  3. Select the origin(s) that have been spamming your site.
  4. Click on "Ban this origin from posting".
  5. Click on "Nuke all comments from this origin".
  6. If you have disabled comments during this maneuver, remember to enable them again.

If the attack is beyond your handling, don't hesitate to contact Infra about the issue.

Help! I deleted my site by accident, what do I do?

Simple answer: You add it back.
Even if a site gets deleted from the control panel, it will still continue to work, although email notifications from the site will be a bit off. To make it re-appear in the control panel, simply re-create the site using the same site ID as before, and you will regain access to its dashboard.

Can I use this system on a non-apache.org site?

Yes, provided it is related to an Apache project. However, due to the inner workings of XMLHTTP requests, you will need to add the oldschool parameter to your HTML snippets to get things working on a non-apache.org site, as such:

<div id="comments_thread"></div>
<script type="text/javascript" 
 src="https://comments.apache.org/show_comments.lua?site=foobar&amp;oldschool=true"
    async="true">
</script>

This parameter informs the comments system builder (the JavaScript that displays the comments on your page) that XMLHTTP requests are not valid for these comments, and a plain POST request will be sent instead.

Comments