tudo

A single version of the truth with integrated task tracking, delegation and accountability.

Why?

We have all experienced working at an organisation where communication, delegation and follow-through were sub-optimal.

tudo is our quest to help all organisations have a "Single version of the truth"" which is always consistent, version-controlled (full audit/history), transparent and real-time.

GitHub OAuth

See: https://developer.github.com/guides/basics-of-authentication/

Sample OAuth access token:

{
  "access_token":"86a6ffa3456b4d7c9020d221a04c66d6f057f007",
  "token_type":"bearer",
  "scope":"repo,user:email"
}

Required Environment Variables

To run this app you will need to set the following environment variables:

• PORT
• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_KEY (this is only temporary)

Local Machine (use a config.env file)

On your personal development machine you can use an config.env file to store these environment variables, create a file called config.env and put it at the root of the project.

This repo contains a sample file: env.json_sample which you can copy:

cp config.env_sample config.env

And then change the values as required. (aksk [@iteles] for access to the Google Doc with our env.json )

Deploying on Heroku

To deploy to Heroku you will need to add the environment variables manually (once)

name

see: https://translate.google.com/#pt/en/tudo

Front-end

Throughout #dwylsummer we worked to pull together the best ideas from everyone into a proposed MVP.

We decided the most valuable thing we could do to improve on the existing github issues page was to add prioritisation.

Our initial whiteboard sketch:

Github API - issues

Please make sure you have an env.json file based upon env.json_sample.

The only issues you will be able to get (for now, until authentication is integrated) are issues that only you can see (or whoever's GitHub access token you're using). These issues can be filtered using the following filters:

• all: to get all the issues a user can see
• assigned: to get all the issues assigned to a user
• created: to get all the issues created by a user
• subscribed: to get all the issues to which a user is subscribed
• mentioned: to get all the issues that mention a user

The default issue object returned by a query to the GitHub API contains a 'comments_url' that links to all the issue's comments. We push the comment information to each issue in the newly created 'comment_items' property.

Issues are returned in an array of objects; an example of issues, including the 'comment_items' property, can be viewed in example_issues.json.

This should be a transferrable function - easily implemented in a handler or incorporated into the existing database functions.

Database Structure

Issues and Users are stored as hashes in Redis.
A user's list of issues is stored as a sorted (by date of update) set.
All users are also stored in an unsorted set.

An issue hash has the following properties:

• id
  
• created_by
• owner_name
• repo_name
• title
• first_line
• labels
  • name
  • color
• updated_at
• created_at
• last_comment
• number_of_comments
• issue_number
• assignee

A user hash has the following properties:

• username

To get a users issues, we have the function in fetch_issues_by_user.js, which adds the user to the database if they don't already exist, and gets their issues, from the database if they are there, otherwise from the github api.

Glossary

Labels

Labels are used to organise issues into logical groups. An issue can have multiple labels. GitHub provide us with the following examples:

• bug: a software defect (incorrect step, process or data definition) that causes a failure.
• duplicate: when the same GitHub issue has been created twice.
• enhancement: is an improvement to a repository( this can be a new feature or a refinement of the code and file structure)
• help wanted: a request for external contribution to an issue with defined objectives from someone within your organization or the GitHub community.
• invalid: issue is not relevant.
• question: A question relating to a repository.
• wontfix: a refusal from another person to fix an issue.

We think issue categorisation through the use of labels can really improve organisation. Here are a few of the dwyl provided labels that we find useful:

Time

• time-estimate:{time in minutes}: the estimated time that you think is needed to complete an issues objectives.
• time-actual:{time in minutes}: the actual time that it took for an issues objectives to be completed.
• time-unestimated: when the an issue has no time-estimate. #### Priority
• priority-1: * the contents of an issue are of highest priority and if it contains tasks they must be completed asap (an example would be a bug which has crashed a live application) .*
• priority-2: not as high a priority as priority-1 but still pretty important.
• priority-3: issues labeled with this are not very important this could include a minor amendment to a sites contents.

Other

• ice-box: *issues that do not have to be acted upon until a later date. *
• dependency: when an something external is preventing an issue from being completed.

Components

Components for the login, home and issue page are located in the views/tags folder. All tags are rendered on the server side by using the render function from Riot.js.