kitsonk / dote

A Community Feature Management Tool

dote

A topic based voting system for open collaboration.

This solution is currently being used to decide the direction of Dojo 2 and is built upon Dojo 1.9 and NodeJS, so it is as much of "eat your own dog-food" as is possible. It is specifically designed to document and make clear decisions and allow a diverse community of contributors to collaborate.

The question of "why re-invent the wheel" when there are other solutions available out there. The biggest and most compelling reason is that the vast majority of them lacked robust e-mail integration. dote attempts, as far as possible to make interaction with the community as rich and flexible via e-mail as it does via the website. This allows each individual to participate fully without having to remember another login, or remind themselves to check another site.

A secondary issue was that most of the tools available out there were for users to demonstrate their support or lack of for "issues" or "features". The Dojo community needed something where the intent of the community was clear, that members could clearly document their thoughts, including rich mark-up and then the topic would be "owned" by an individual and decided upon. While other tools came close to this model, none of them were exactly the governance model that was used by the community.

Requirements

dote depends on the following projects:

• express - HTTP Server Framework
• jade - HTML Templating
• Stylus - CSS Templating
• Nib - CSS3 Enhancements for Stylus
• Font-Awesome - Font Based Icons
• Dojo Toolkit - JavaScript Framework
• setten - Dojo-style Modules for Node
• ComposeJS - JavaScript Object Composition
• Persevere - Storage Abstraction Layer
• Moment.js - Date Handling (including humanisation)
• marked - markdown Parser
• Highlight.js - Code Block Highlighting
• emailjs - NodeJS STMP Client
• node-imap - NodeJS IMAP Client
• mailparser - Mail Parsing Library
• feed - RSS and Atom generator
• node-mongodb-native - Node Native MongoDB Library
• juice - Inlining CSS into HTML
• ldapauth - LDAP Authorisation
• colors - Node Console Colors
• MongoDB - Persistent Document Store

You will need git and NodeJS including npm to properly install dote. dote has been tested on NodeJS 0.8.4 - 0.8.15 and 0.10.5.

Installation

• Install MongoDB and have available.

• Clone the repository recursively with git:

  $ git clone --recursive https://github.com/kitsonk/dote.git

• Install NodeJS dependencies with npm:

  $ cd dote
  $ npm install

• Edit the config.json in the root directory.

• Set the passwords in the environment:

  $ export DOTE_LDAP_PWD="password"
  $ export DOTE_MAIL_PWD="password"

• Start the server:

  $ node server

• Start the worker:

  $ node worker

Optimised Client Build

dote allows you to utilise the Dojo Builder to optimise the client side JavaScript that is used. In order to utilise the optimised build, run the builder (which is not included):

$ path/to/dtk/util/buildScripts/build.sh --profile dote.profile.js

This will output an optimised build to ./lib/. Then you need to point the instance at it by changing the base parameter in the config.json file:

{
    "base": "lib"
}

And changing the _static/css/dote.styl to point at the optimised CSS:

@import url("../../lib/dote-client/resources/client.css")

Notes

• dote respects the NODE_ENV and maps this appropriately to the configuration file, defaulting to development.
• While the LDAP and mail password can be set in the config.json but they will be overridden by any environment variable. You generally shouldn't store clear text passwords in static files.
• There are 3 types of authentication support (auth in the configuration). There is default which simply means all passwords are set to "password", there is internal which stores passwords as a SHA512 digest with an added salt string and there is ldap which hands off authentication to the LDAP server configured in the files.
• If using the internal password/authorization instead of LDAP, you should set the NODE_SALT environment variable to an appropriate salt. If not provided, the salt for the passwords defaults to the one stored in plain text in the code, which isn't advised. Of course if you change, or lose the salt for your environment, no passwords digest properly, which means no one will be able to log in.

dote's Issues

Static Links to comments not working on non-archive pages

Ideally the Topic widget should identify the hash link to the static comment and ensure that that topic is loaded and scroll to it. Right now, it just plops you on the page.

Closed actions should be hidden by default.

Closed actions should be hidden from view by default.

There should be just a closed action.

Sometimes, it is just fine to "close" and action, without actually rejecting or accepting it.

Wrapping issues on Topic with voters

The voter tags are not wrapping properly in the topic view. They are fine in the TopicList view.

Daily Digests

@ttrenka suggested that daily digests of activity would be a good idea. I agree.

There should be a way for Admins to edit Topic descriptions.

The admin interface should include a way to edit topic descriptions and should notify people of changes to topic titles and descriptions.

Topic Actions not being set

It appears that when actions are posted to the server, they are not being properly set. I suspect it has to do with the conflict resolution I placed in the code.

Have a "timeline" view.

@neonstalwart and @bryanforbes suggested a timeline view of dote. I am taking that to assume each activity is presented in a reverse timeline order, so you would have something like:

• Topic Replace JavaScript with TypeScript for Dojo 2 was Accepted
• jeff was assigned as owner on Replace JavaScript with TypeScript for Dojo 2
• sally comment on Replace JavaScript with TypeScript for Dojo 2
• bob voted +1 on Replace JavaScript with TypeScript for Dojo 2
• Topic Replace JavaScript with TypeScript for Dojo2 created

Topic Actions are not E-mailed

Currently the worker does not process topic actions. It reports Unsupported Topic Change.

E-Mail Replies don't strip signatures...

Processed e-mails should strip signatures, when they are in the format:

Here is the content
--
Something below the two (or more dashes) should be stripped

Order Topic view my most recently changed

@neonstalwart and @bryanforbes suggested that topics should be listed in reverse "last modified" order, so that the topic with the most recent activity is listed at the top.

Users changed to committers votes don't reflect

When a user is flagged as a committer, the previous topics which they have voted on don't change to reflect their status, even if they change their vote.

The ability to filter topics by free text search.

Topics should be able to be filtered by free text search, in the title and description fields.

Putting conflict resolution

If someone has a local copy of an item, and attempts to POST it, it simply overwrites the previous version, undoing any other subsequent changes to that document that have gone on.

The ability to see "real names" for users

The ability to view real names versus just login names for users and votes.

Topics do not refresh properly on website when changed via e-mail

Topics do not invalidate properly when they are updated in the worker process versus the server process. This is because the topic object caches the topics in process memory but has no way of detecting it should be invalidated when modified in another process.

Support Attachments

@wkeese suggested that dote should support attachments. I agree that this should be added in the future.

Provide a RSS feed for Events and Topics

Provide an RSS feed for Events and topics, so that people can keep up to date.

Add the ability to remove a vote

Colin mentioned in the "Let's start using Dote" email thread that the ability to actually remove a vote (as opposed to setting it to +0) might be a good thing...

Only include committers in total vote count...

Having committers and non-committers in votes is useful to a degree, but it does cloud the issues of what the overall sentiment is. I guess there should just be a calculation of the committers in the overall count, or two totals should be displayed, both a committer and and all voter vote.

Also potentially add the option to only e-mail when a committer votes.

Comment Count Doesn't Increment when Added via e-mail

E-mail comments don't increment the comment count field.