feature: refactor API to be more uniform

* Update npm for publishing
* Update changelog to reflect the breaking changes
* Update travis.yml to properly run tests
* Update jsdoc config

Author: clayreimann

.babelrc

@@ -8,7 +8,7 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 
-[*.yml,package.json]
+[{*.yml,package.json}]
 indent_size = 2
 
 [*.md]

.editorconfig

@@ -2,10 +2,7 @@ docs/
 dist/
 coverage/
 node_modules/
-.nyc_output/
 
 .DS_Store
-.idea
-.zuulrc
 npm-debug.log
 sauce.json

.gitignore

@@ -3,7 +3,7 @@
         "dictionaries": ["jsdoc"]
     },
     "source": {
-        "include": ["src", "package.json", "README.md"],
+        "include": ["lib/", "package.json", "README.md"],
         "includePattern": ".js$",
         "excludePattern": "(node_modules/|docs)"
     },

.jsdoc.json

@@ -0,0 +1,6 @@
+docs/
+coverage/
+node_modules/
+
+.DS_Store
+sauce.json

.npmignore

@@ -1,21 +1,27 @@
 language: node_js
-
-sudo: false
-
 node_js:
-  - "5.7"
-  - "4.3"
-  - "0.12"
-  - "0.10"
-
+  - '5'
+  - '4'
+  - '0.12'
+  - '0.10'
 cache:
   directories:
     - node_modules
-
-before_install:
-  - npm install -g npm@latest
-
+before_install: npm install -g npm@latest
+before_script:
+  - npm run lint
+  # - npm run build # will need this when we do sauce testing of compiled files
 script:
-  - gulp lint
-  - gulp test:mocha
-  # - npm run codecov # disabled temporarialy while I work out how to generate accurate coverage of ES2015 code
+  - npm test
+  # - npm run test-dist # test the compiled files
+# after_success:
+#   - npm run codecov # disabled temporarialy while I work out how to generate accurate coverage of ES2015 code
+before_deploy:
+    - npm run build
+deploy:
+  provider: npm
+  skip_cleanup: true
+  on:
+    tags: true
+  api_key:
+    secure: TZHqJ9Kh2Qf0GAVDjEOQ01Ez6rGMYHKwVLOKTbnb7nSzF7iiGNT4UwzvYawm0T9p1k7X1WOqW3l7OEbIwoKl7/9azT4BBJm7qUMRfB9Zio5cL3rKubJVz7+LEEIW4iBeDWLanhUDgy9BO2JKCt8bfp/U2tltgXtu9Fm/UFPALI8=

.travis.yml

@@ -6,13 +6,51 @@ Complete rewrite in ES2015.
 * Promise-ified the API
 * Auto-generation of documentation
 * Modularized codebase
-* Refactored tests to run primarially in mocha
+* Refactored tests to run primarily in mocha
 
 #### Breaking changes
-* Search API no longer takes a string it now takes an object with properties `q`, `sort`, and `order` to make
-   the parts of the query easier to grok and to better match GitHub's API
-* `Repository.getSha` now returns the same data as GitHub's API. If the reqeusted object is not a directory then the
-   response will contain a property `SHA`, and if the reqeusted object is a directory then the contents of the
-   directory are `stat`ed
+Most of the breaking changes are just methods that got renamed. The changes to `User` and `Organization` are deeper
+changes that now scope a particular `User` or `Organization` to the entity they were instantiated with. You will need
+separate `User`s to query data about different user accounts.
+
+* `Github.getOrg` → `Github.getOrganization` and requires an organization name.
+* `Github.getUser` now requires a username.
+* `Issue.comment` → `Issue.createIssueComment`
+* `Issue.create` → `Issue.createIssue`
+* `Issue.edit` → `Issue.editIssue`
+* `Issue.get` → `Issue.getIssue`
+* `Issue.list` → `Issue.listIssues`
+* `Repository.branch` → `Repository.createBranch`
+* `Repository.collaborators` → `Repository.getCollaborators`
+* `Repository.compare` → `Repository.compareBranches`
+* `Repository.contents` → `Repository.getContents` and now takes an argument for the content type
+* `Repository.delete` has been removed.
+* `Repository.editHook` → `Repository.updateHook`
+* `Repository.editRelease` → `Repository.updateRelease`
+* `Repository.getCommit` no longer takes a branch as the first argument
+* `Repository.getPull` → `Repository.getPullRequest`
 * `Repository.getRef` now returns the `refspec` from GitHub's API.
-* `Repository.delete` has been removed
+* `Repository.getSha` now returns the same data as GitHub's API. If the reqeusted object is not a directory then the
+   response will contain a property `SHA`, and if the reqeusted object is a directory then the contents of the directory
+   are `stat`ed.
+* `Repository.getStatuses` → `Repository.listStatuses`
+* `Repository.listPulls` → `Repository.listPullRequests`
+* `Repository.postBlob` → `Repository.createBlob`
+* `Repository.postTree` → `Repository.createTree`
+* `Repository.read` remove in favor of `Repository.getContents`
+* `Repository.remove` → `Repository.deleteFile`
+* `Repository.show` → `Repository.getDetails`
+* `Repository.write` → `Repository.writeFile`
+* `Search.code` → `Search.forCode`
+* `Search.issues` → `Search.forIssues`
+* `Search.repositories` → `Search.forRepositories`
+* `Search.users` → `Search.forUsers`
+* The Search API no longer takes a string, it now takes an object with properties `q`, `sort`, and `order` to make the
+   parts of the query easier to grok and to better match GitHub's API.
+* `User.gists` → `User.getGists`
+* `User.notifications` → `User.getNotifications`
+* `User.orgRepos` → `Organization.getRepos`
+* `User.orgs` → `User.getOrgs`
+* `User.repos` → `User.getRepos`
+* `User.show` → `User.getProfile` and no longer takes filtering options
+* `User.userStarred` → `User.getStarredRepos`

CHANGELOG.md

@@ -17,25 +17,86 @@ npm install github-api
 ```
 
 ## Compatibility
-
-[![Sauce Test Status](https://saucelabs.com/browser-matrix/githubjs.svg)](https://saucelabs.com/u/githubjs)
-
-**Note**: Starting from version 0.10.8, Github.js supports **Internet Explorer 9**. However, the underlying methodology
-used under the hood to perform CORS requests (the `XDomainRequest` object), [has limitations](xhr-link).
-In particular, requests must be targeted to the same scheme as the hosting page. This means that if a page is at
-http://example.com, your target URL must also begin with HTTP. Similarly, if your page is at https://example.com, then
-your target URL must also begin with HTTPS. For this reason, if your requests are sent to the GitHub API (the default),
-which are served via HTTPS, your page must use HTTPS too.
+Github.js is tested on Node:
+* 0.10
+* 0.12
+* 4.x
+* 5.x
 
 ## GitHub Tools
 
 The team behind Github.js has created a whole organization, called [GitHub Tools](https://github.com/github-tools),
 dedicated to GitHub and its API. In the near future this repository could be moved under the GitHub Tools organization
 as well. In the meantime, we recommend you to take a look at other projects of the organization.
 
-## Example
+## Samples
+
+```javascript
+/*
+   Data can be retrieved from the API either using callbacks (as in versions < 1.0)
+   or using a new promise-based API. For now the promise-based API just returns the
+   raw HTTP request promise; this might change in the next version.
+ */
+var GitHub = require('github-api');
+
+// unauthenticated client
+var gh = new GitHub();
+var gist = gh.getGist(); // not a gist yet
+gist.create({
+   public: true,
+   description: 'My first gist',
+   files: {
+      "file1.txt": {
+         contents: "Aren't gists great!"
+      }
+   }
+}).then(function(httpResponse) {
+   // Promises!
+   var gist = httpResponse.data;
+   gist.read(function(err, gist, xhr) {
+      // if no error occurred then err == null
+
+      // gist == httpResponse.data
+
+      // xhr == httpResponse
+   });
+});
+```
+
+```javascript
+var GitHub = require('github-api');
 
-**TODO**
+// basic auth
+var gh = new GitHub({
+   username: 'FOO',
+   password: 'NotFoo'
+});
+
+var me = gh.getUser();
+me.getNotification(function(err, notifcations) {
+   // do some stuff
+});
+
+var clayreimann = gh.getUser('clayreimann');
+clayreimann.getStarredRepos()
+   .then(function(httpPromise) {
+      var repos = httpPromise.data;
+   });
+```
+
+```javascript
+var GitHub = require('github-api');
+
+// token auth
+var gh = new GitHub({
+   token: 'MY_OAUTH_TOKEN'
+});
+
+var yahoo = gh.getOrganization('yahoo');
+yahoo.getRepos(function(err, repos) {
+   // look at all the repos!
+})
+```
 
 [cdnjs]: https://cdnjs.com/
 [codecov]: https://codecov.io/github/michael/github?branch=master

README.md

@@ -6,14 +6,14 @@ import stylish from 'gulp-jscs-stylish';
 import babel from 'gulp-babel';
 import rename from 'gulp-rename';
 
-import browserify  from 'browserify';
-import buffer  from 'vinyl-buffer';
-import del  from 'del';
-import path  from 'path';
+import browserify from 'browserify';
+import buffer from 'vinyl-buffer';
+import del from 'del';
+import path from 'path';
 import {Promise}  from 'es6-promise';
-import source  from 'vinyl-source-stream';
-import sourcemaps  from 'gulp-sourcemaps';
-import uglify  from 'gulp-uglify';
+import source from 'vinyl-source-stream';
+import sourcemaps from 'gulp-sourcemaps';
+import uglify from 'gulp-uglify';
 
 const ALL_SOURCES = [
    path.join(__dirname, '/*.js'),
@@ -37,51 +37,69 @@ gulp.task('clean', function() {
    return Promise.all([del('dist/'), del('coverage/')]);
 });
 
-const browserifyConfig = {
+gulp.task('build', [
+   'build:bundled:min',
+   'build:external:min',
+   'build:bundled:debug',
+   'build:external:debug',
+   'build:components'
+]);
+
+const bundledConfig = {
    debug: true,
-   entries: 'src/Github.js',
-   standalone: 'Github'
+   entries: 'lib/GitHub.js',
+   standalone: 'GitHub'
 };
-gulp.task('build', function() {
-   browserify(browserifyConfig)
-      .transform('babelify')
-      .bundle()
-      .pipe(source('Github.js'))
-      .pipe(buffer())
-      .pipe(sourcemaps.init({
-         loadMaps: true
-      }))
-      .pipe(uglify())
-      .pipe(rename({
-         extname: '.bundle.min.js'
-      }))
+const externalConfig = {
+   debug: true,
+   entries: 'lib/GitHub.js',
+   standalone: 'GitHub',
+   external: [
+      'axios',
+      'js-base64',
+      'es6-promise',
+      'debug',
+      'utf8'
+   ],
+   bundleExternal: false
+};
+gulp.task('build:bundled:min', function() {
+   return buildBundle(bundledConfig, '.bundle.min.js', true);
+});
+gulp.task('build:external:min', function() {
+   return buildBundle(externalConfig, '.min.js', true);
+});
+gulp.task('build:bundled:debug', function() {
+   return buildBundle(bundledConfig, '.bundle.js', false);
+});
+gulp.task('build:external:debug', function() {
+   return buildBundle(externalConfig, '.js', false);
+});
+gulp.task('build:components', function() {
+   return gulp.src('lib/*.js')
+      .pipe(sourcemaps.init())
+      .pipe(babel())
       .pipe(sourcemaps.write('.'))
-      .pipe(gulp.dest('dist'))
+      .pipe(gulp.dest('dist/components'))
       ;
+});
 
-   browserify(browserifyConfig)
+function buildBundle(options, extname, minify) {
+   let stream = browserify(options)
       .transform('babelify')
       .bundle()
-      .pipe(source('Github.js'))
+      .pipe(source('GitHub.js'))
       .pipe(buffer())
       .pipe(sourcemaps.init({
          loadMaps: true
-      }))
-      .pipe(rename({
-         extname: '.bundle.js'
-      }))
-      .pipe(sourcemaps.write('.'))
-      .pipe(gulp.dest('dist'))
-      ;
+      }));
 
-   return gulp.src('src/*.js')
-      .pipe(babel())
-      .pipe(sourcemaps.init())
+   if (minify) {
+      stream = stream.pipe(uglify());
+   }
+
+   return stream.pipe(rename({extname}))
       .pipe(sourcemaps.write('.'))
-      .pipe(gulp.dest('dist/components'))
+      .pipe(gulp.dest('dist'))
       ;
-});
-
-gulp.task('default', ['clean'], function() {
-   gulp.start('lint', 'test:mocha', 'build');
-});
+}