ubervu / github-changelog Goto Github PK

Need

The easiest way to integrate the changelog on the client-side is through a jQuery plugin

Deliverables

• jQuery plugin that generates the DOM in a given container

The jQuery plugin will support the following options:

// Checks GitHub for new updates since last fetch
$('.changelog-container').changelog({
  // Label for the button the appears when you got updates, supports HTML
  buttonText: 'Click me, I got updates!',
  // Label for the reload button shown below the list, supports HTML
  reloadButtonText: 'Reload',
  // Position of the list around the button. E.g. if the button is placed 
  // on the bottom-right corner, you probably want the list to be positioned 
  // top-left or left-top
  listPosition: 'top-left',
  // Poll GitHub for new updates at every set number of seconds
  autoRefresh: 2,
  // GitHub repository to fetch issues from
  githubRepo: 'facebook/react',
  // Only show updates that have one of these labels
  githubLabels: ['bug', 'enhancement', 'feature'],
  // Payload for the GitHub issues endpoint 
  // https://developer.github.com/v3/issues/#list-issues
  githubParams: {
    // Only get issues from GitHub that have ALL of these labels
    // It's best to set a single label here, e.g. 'release', that's common
    // to all issues. For deeper filtering 'githubLabels' can be used
    labels: 'release'
  }
});

The jQuery plugin will have the following methods:

// Checks GitHub for new updates since last fetch
$('.changelog-container').changelog('checkForUpdates');

Solution

We need to have a container which in the first place will be empty, this will be targeted by the plugin.

Second, we need to make a jQuery plugin, which will have a method called checkForUpdates. Given options set by the user(see above), it will be able to poll GitHub and generate the appropriate DOM structure when issues are closed.
For a given repository (gitHubRepo) and a common label set under githubParams.labels this method will request the issues that were closed since a given timestamp. The timestamp will be set when the plugin is first initialized on a container and reset after new updates are received.

Prerequisites

• jQuery Plugins
• GitHub API

TODO

• create the skeleton for the plugin
• create the default options for the plugin
• apply custom options passed through changelog plugin
• create a method which will append the changelog DOM to the container
• create a method which will trigger click event on the button and toggle the list
• create checkForUpdates method
• create a destroy method that unbinds event listeners and removes the changelog DOM
• add support for GitHub API

cc: @skidding @RadValentin

Need

Build a HTML structure for the widget that allows for customization and that can be used by the plugin

Deliverables

• Add info in README.md detailing the HTML structure

Solution

We will have the plugin contained within a wrapper called changelog-wrapper. Inside of it there are two elements:

1. Notification button - This is what shows up when new notifications are available.
2. Notification list - This list shows the notification area, it will contain number of notification items.

The button will contain a badge that will show the number of new notifications. The list will be made up of multiple items, each corresponding to a notification. The list can be positioned using a class on the wrapper. There will also be a footer inside the list that will contain the reload button.

Notification item - composed of two elements, a label and text content.

TODO

• define a notification button with a badge
• define options to style the button: size and type
• define a notification list
• define a notification item with content text and an optional label
• define options for positioning the list in relation to the button
• define an element to contain a reload button (list footer)

cc: @skidding @catalinmiron

Need

As a developer
I want clean maintainable code
So that I can be more productive.

Deliverables

Clean code.

Solution

Refactor all the things!

Main issue: #2

Need

We need to use the GitHub data people are already using to offer a transparent status update system for their customers, without building an additional admin panel for those status updates.

Deliverables

• A method that returns titles and labels from issues that have a certain label and were referenced in merge commits from a given branch, newer than a given timestamp.

Ex: For timestamp: '1400251736447', branch: 'master' and label: 'release' the method would go through the following steps:

• We get all commits from master newer than 1400251736447, from a given repo
• We filter out commits that don't have the release label
• We filter out non-merge commits (maybe we have a way to figure that out, worst case by matching commit message)
• All commits have an issue reference inside their message, e.g. Solve yata yata #11340 that basically references to github.com/org/repo/issues/11340
• We extract the ID from the that string, for each merge commit we're left with after applying the previous filters
• We query GitHub for each of the issue IDs we care about and return the title and all the other labels it has (besides release, of course)

The output would then look something like this:

[{title: "Fix overlapping text", labels: ['bug', 'client', 'moderate']},
 {title: "Create geo map visualization", labels: ['feature']}]

Solution

Given an timestamp, branch and label we need to build the following functionality:

1. A method to get all merge commits since the given timestamp (filter by branch) and filter out commits that don't have the label
2. A method to extract issue meta data from commit issue ID reference (ex: #3351)
3. A method to filter issues by label
4. A method to return title and label that the plugin can use to populate the notification list

Prerequisites

• GitHub API
  • List commits on a repository
  • Get a single issue
  • Traversing with pagination
  • API rate limiting
• jQuery Plugins
• How to access private repos through the GitHub API?
• How to insert needed credentials to access private repos?
• How to check all merged pull-requests into a branch?
• How to filter pull-requests by timestamp?
• How to extract issue id from a pull-request?
• How to filter issues by label?
• How to get issue info for use in the plugin?

TODO

• Research prerequisites, answer questions
• Implement GitHub authentication
• Implement a way to check merged pull-requests
• Implement filtering by timestamp on pull-requests
• Implement a way to extract issue id from a pull-request
• Implement a way to filter issues by label

cc: @skidding @catalinmiron

Need

All github users should be able to run the demo and see it working without needing admin access to ubervu

Solution

Because of the way github works, a user that's not part of ubervu can set issues on the playground but he won't be able to set labels on that issue. This limitation makes the demo unusable for outside users.
We need to figure out a way will allow any user to run the demo.

Possible solutions:

1. Add a disclaimer on the demo page that informs users about this limitation, and that shows an image(gif) of how the plugin works.
2. Hardcode a default label into the demo and make the plugin pull in all issues from the playground. Even if a user can't set a label, he'll still get a notification with the default label.
3. Add an extra step to the demo instructions with an input field for a repository (defaults to playground). This way a user can run the demo on his own repo. We could also make use of local storage to store this repo name so the demo still works after page reload.

cc: @skidding @catalinmiron

Need

Build LESS styling to support the HTML structure so that it can be integrated with the plugin

Deliverables

• LESS files and the generated CSS for positioning and styling the notification list. The styling will be applied to the HTML structure described below and should match the attached wireframe.

HTML structure

<div class="github-changelog">
  <a class="github-changelog-btn" href="#">
    New updates!
    <span class="github-changelog-badge">2</span>
  </a>

  <div class="github-changelog-list">
    <ul>
      <li>
        <span class="github-changelog-label"> issue label </span>
        <p> issue title </p>
      </li>
    </ul>
    <div class="github-changelog-footer">
      <a class="github-changelog-btn github-changelog-btn-reload">Reload</a>
    </div>
  </div>
</div>

Wireframe

Solution

We'll need to create styling for the following:

1. A notification button with a badge to show the number of new notifications
2. A notification list that can be positioned according to it's css class with 4 main positions: top, bottom, left and right. Each of these positions can be modified by providing a second class: pull-left and pull-right for vertical positions and pull-top for horizontal positions. The purpose here is to make the list usable in any positioning scenario.
3. A footer element for the notification list that will contain a reload button.
4. Notification items that will show up in the list. These will have a label and content text.
5. A utility class .closed to hide the list

Prerequisites

• LESS
• Compile LESS to CSS Grunt plugin
• HTML Structure wiki page

TODO

• Create a LESS skeleton to support the HTML structure
• Add styles for the button, its appearance and size
• Extend the button styling to support a badge element
• Add styles for the notification list
• Add styles for positioning the notification list
• Add styles for the notification list footer
• Define LESS variables for changing the various styling options
• Define utility class to hide the list

cc: @skidding @catalinmiron

Steps

1. Open the index.html file.
2. Open and close an issue in the playground repo.
3. Repeatedly press the Check for updates button very fast.
4. The badge number will continue to increment with every press.
5. Pause for a while.
6. Press the button again.
7. The badge number will not increment.

Let's see if we can simplify our primitives.

We have both "Notification button" (wiki) and "Notification icon" (readme). Are they two things or the same? Let's use only one if so. I like "button" more.

"Notifications" or "updates"? I think when it comes to software you have "updates", "notifications" are more related to activities that happen inside the app (Facebook, etc.)

Here's an example of saying nothing:

Notification item

One element of the notification list.

Item, element, list, even notification, are all abstract words you have to run away from. Then you have joint words of, the, etc., so no concrete word at all. Element of what? Item of what? List of what? etc.

Here's a sentence that stands by itself:

The list is made out of app updates that were released since the last time the user hard-refreshed the app. Each update entry corresponds to a closed GitHub issue.

Need

As a user
I want to be able to get notifications about new changes to an application
So that I can stay informed and be able to reload the application at my own will

Deliverables

inspiration from github on mac

• A jquery plugin which can check for updates on a GitHub project and notify the user by inserting and updating the notification list
• A HTML structure for the list
• A LESS / CSS library to provide styling for the list

Prerequisites

• GitHub API
• jQuery Plugins
• LESS

Notes

1. Add default position to list, when no positioning classes are provided?
2. Notification button doesn't show up by default, only when there are notifications to be shown
3. All visual elements should have default styling but need to also be customizable. Right now this can be done via the variables in variables.less. Should we extend this further?
4. Reload button(see screenshot above). We need to discuss how to add a header that will contain the reload button and maybe a title. This can't be part of the ul, needs to be a separate element so that it doesn't scroll with the list.

cc: @uberVU/ux @RadValentin