new license and updating docs

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+
+# Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

azure-pipelines.release.yml

@@ -0,0 +1,39 @@
+# Node.js
+# Build a general Node.js project with npm.
+# Add steps that analyze code, save build artifacts, deploy, and more:
+# https://docs.microsoft.com/azure/devops/pipelines/languages/javascript
+
+pr: none
+
+trigger:
+  - master
+
+pool:
+  vmImage: 'Ubuntu-16.04'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '10.x'
+    displayName: 'Install Node.js'
+
+  - script: |
+      git config user.email "kchau@microsoft.com"
+      git config user.name "kchau@microsoft.com"
+      git remote set-url origin https://$(github.user):$(github.pat)@github.com/kenotron/beachball.git
+    displayName: 'git config'
+  - script: |
+      yarn
+    displayName: 'yarn'
+  - script: |
+      yarn checkchange
+    displayName: 'check change files'
+  - script: |
+      yarn build
+    displayName: 'build'
+  - script: |
+      yarn test
+    displayName: 'test'
+  - script: |
+      yarn publish:beachball -n $(npm.authtoken) -y
+    displayName: 'beachball publish'

docs/page-data/bump/page-data.json

@@ -1 +1 @@
-{"componentChunkName":"component---src-templates-doc-jsx","path":"/bump","webpackCompilationHash":"f24aab57cd054fc5bc5c","result":{"data":{"postBySlug":{"html":"<p>Bumps versions locally without publishing to the remote git repo or npm registry. This command will also generate changelogs. By using this command, it is up to you to synchronize the package versions in the remote git repo as well as the npm registry.</p>","frontmatter":{"title":"bump"}},"tableOfContents":{"chapters":[{"title":"Overview","entries":[{"entry":{"id":"aa948e6b-0177-51ab-877c-de4df9879e2e","childMarkdownRemark":{"fields":{"slug":"/getting-started"},"frontmatter":{"title":"Getting Started"}}}},{"entry":{"id":"ccfd1734-230c-5de7-8188-b9c9f36c34e9","childMarkdownRemark":{"fields":{"slug":"/installation"},"frontmatter":{"title":"Installation"}}}},{"entry":{"id":"b89feaf8-14d3-5a12-a574-31fa91dc785e","childMarkdownRemark":{"fields":{"slug":"/change-files"},"frontmatter":{"title":"Change Files"}}}},{"entry":{"id":"ed6560cb-8495-5c33-a16d-6698913b2ceb","childMarkdownRemark":{"fields":{"slug":"/ci-integration"},"frontmatter":{"title":"CI Integration"}}}}]},{"title":"CLI Reference","entries":[{"entry":{"id":"d331b943-d44c-57ee-b77c-45d0ac5a7a0d","childMarkdownRemark":{"fields":{"slug":"/change"},"frontmatter":{"title":"change"}}}},{"entry":{"id":"25b6911e-bac6-5692-80eb-8c70d1863000","childMarkdownRemark":{"fields":{"slug":"/check"},"frontmatter":{"title":"check"}}}},{"entry":{"id":"e9d2f246-5b07-5abe-92a6-d65c4c4e8ac4","childMarkdownRemark":{"fields":{"slug":"/bump"},"frontmatter":{"title":"bump"}}}},{"entry":{"id":"22b3b9a8-e74d-5bdf-83ad-d25cfbe60715","childMarkdownRemark":{"fields":{"slug":"/publish"},"frontmatter":{"title":"publish"}}}},{"entry":{"id":"55c11620-e2b0-538d-b36d-f5897681b65a","childMarkdownRemark":{"fields":{"slug":"/options"},"frontmatter":{"title":"options"}}}}]}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"/bump"}}}
+{"componentChunkName":"component---src-templates-doc-jsx","path":"/bump","webpackCompilationHash":"f24aab57cd054fc5bc5c","result":{"data":{"postBySlug":{"html":"<p>Bumps versions locally without publishing to the remote git repo or npm registry. This command will also generate changelogs.</p>\n<p>This is the same logic that is used by the publish command, so it is a good practice to bump things locally to see what kind of changes are going to be done before those changes are published to the npm registry and the remote git repo. Since this affects files locally only, it is up to you to synchronize the package versions in the remote git repo as well as the npm registry.</p>\n<div class=\"gatsby-highlight\" data-language=\"bash\"><pre class=\"language-bash\"><code class=\"language-bash\">$ beachball bump</code></pre></div>","frontmatter":{"title":"bump"}},"tableOfContents":{"chapters":[{"title":"Overview","entries":[{"entry":{"id":"aa948e6b-0177-51ab-877c-de4df9879e2e","childMarkdownRemark":{"fields":{"slug":"/getting-started"},"frontmatter":{"title":"Getting Started"}}}},{"entry":{"id":"ccfd1734-230c-5de7-8188-b9c9f36c34e9","childMarkdownRemark":{"fields":{"slug":"/installation"},"frontmatter":{"title":"Installation"}}}},{"entry":{"id":"b89feaf8-14d3-5a12-a574-31fa91dc785e","childMarkdownRemark":{"fields":{"slug":"/change-files"},"frontmatter":{"title":"Change Files"}}}},{"entry":{"id":"ed6560cb-8495-5c33-a16d-6698913b2ceb","childMarkdownRemark":{"fields":{"slug":"/ci-integration"},"frontmatter":{"title":"CI Integration"}}}}]},{"title":"CLI Reference","entries":[{"entry":{"id":"d331b943-d44c-57ee-b77c-45d0ac5a7a0d","childMarkdownRemark":{"fields":{"slug":"/change"},"frontmatter":{"title":"change"}}}},{"entry":{"id":"25b6911e-bac6-5692-80eb-8c70d1863000","childMarkdownRemark":{"fields":{"slug":"/check"},"frontmatter":{"title":"check"}}}},{"entry":{"id":"e9d2f246-5b07-5abe-92a6-d65c4c4e8ac4","childMarkdownRemark":{"fields":{"slug":"/bump"},"frontmatter":{"title":"bump"}}}},{"entry":{"id":"22b3b9a8-e74d-5bdf-83ad-d25cfbe60715","childMarkdownRemark":{"fields":{"slug":"/publish"},"frontmatter":{"title":"publish"}}}},{"entry":{"id":"55c11620-e2b0-538d-b36d-f5897681b65a","childMarkdownRemark":{"fields":{"slug":"/options"},"frontmatter":{"title":"options"}}}}]}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"/bump"}}}

docs/page-data/index/page-data.json

@@ -1 +1 @@
-{"componentChunkName":"component---src-pages-index-jsx","path":"/","webpackCompilationHash":"f24aab57cd054fc5bc5c","result":{"data":{"allMarkdown":{"edges":[{"node":{"fields":{"slug":"/bump"},"excerpt":"Bumps versions locally without publishing to the remote git repo or npm registry. This command will also generate changelogs. By using this…","frontmatter":{"title":"bump"}}},{"node":{"fields":{"slug":"/change"},"excerpt":"This command walks you through a couple of questions and will generate the appropriate change file in the  directory. The generated file…","frontmatter":{"title":"change"}}},{"node":{"fields":{"slug":"/check"},"excerpt":"It is useful to enforce that change files are checked in for each PR before they enter the target branch. In this way, all changes are…","frontmatter":{"title":"check"}}},{"node":{"fields":{"slug":"/options"},"excerpt":"This is a listing of all the options available. Not every option applies to all the commands.All Beachball CLI Optionsregistry, defaults to…","frontmatter":{"title":"options"}}},{"node":{"fields":{"slug":"/publish"},"excerpt":"","frontmatter":{"title":"publish"}}},{"node":{"fields":{"slug":"/change-files"},"excerpt":"There are very popular and excellent packages available which manage package versioning already. Beachball works differently:  does _not…","frontmatter":{"title":"Change Files"}}},{"node":{"fields":{"slug":"/ci-integration"},"excerpt":"","frontmatter":{"title":"CI Integration"}}},{"node":{"fields":{"slug":"/getting-started"},"excerpt":"Javascript ecosystem moves fast. It moves so fast that sometimes the tools need to catch up to it. One of the reasons that this particular…","frontmatter":{"title":"Getting Started"}}},{"node":{"fields":{"slug":"/installation"},"excerpt":"There are two options to install .Option 1: no installThanks to , you can use  without any installation:Option 2: Install and Run as NPM…","frontmatter":{"title":"Installation"}}}]}},"pageContext":{"isCreatedByStatefulCreatePages":true}}}
+{"componentChunkName":"component---src-pages-index-jsx","path":"/","webpackCompilationHash":"f24aab57cd054fc5bc5c","result":{"data":{"allMarkdown":{"edges":[{"node":{"fields":{"slug":"/bump"},"excerpt":"Bumps versions locally without publishing to the remote git repo or npm registry. This command will also generate changelogs.This is the…","frontmatter":{"title":"bump"}}},{"node":{"fields":{"slug":"/check"},"excerpt":"It is useful to enforce that change files are checked in for each PR before they enter the target branch. In this way, all changes are…","frontmatter":{"title":"check"}}},{"node":{"fields":{"slug":"/options"},"excerpt":"This is a listing of all the options available. Not every option applies to all the commands.All Beachball CLI Optionsregistry, defaults to…","frontmatter":{"title":"options"}}},{"node":{"fields":{"slug":"/publish"},"excerpt":"Publishing automates all the bumping and synchronizing of package versions in git remotes as well as the npm registry. The steps taken by…","frontmatter":{"title":"publish"}}},{"node":{"fields":{"slug":"/getting-started"},"excerpt":"Javascript ecosystem moves fast. It moves so fast that sometimes the tools need to catch up to it. One of the reasons that this particular…","frontmatter":{"title":"Getting Started"}}},{"node":{"fields":{"slug":"/change-files"},"excerpt":"There are very popular and excellent packages available which manage package versioning already. Beachball works differently:  does _not…","frontmatter":{"title":"Change Files"}}},{"node":{"fields":{"slug":"/ci-integration"},"excerpt":"For the repository and package owners or admins who want to automate the bumping of versions based on change files with , you'll need to…","frontmatter":{"title":"CI Integration"}}},{"node":{"fields":{"slug":"/installation"},"excerpt":"There are two options to install .Option 1: no installThanks to , you can use  without any installation:Option 2: Install and Run as NPM…","frontmatter":{"title":"Installation"}}},{"node":{"fields":{"slug":"/change"},"excerpt":"This command walks you through a couple of questions and will generate the appropriate change file in the  directory. The generated file…","frontmatter":{"title":"change"}}}]}},"pageContext":{"isCreatedByStatefulCreatePages":true}}}

docs/page-data/publish/page-data.json

@@ -1 +1 @@
-{"componentChunkName":"component---src-templates-doc-jsx","path":"/publish","webpackCompilationHash":"f24aab57cd054fc5bc5c","result":{"data":{"postBySlug":{"html":"","frontmatter":{"title":"publish"}},"tableOfContents":{"chapters":[{"title":"Overview","entries":[{"entry":{"id":"aa948e6b-0177-51ab-877c-de4df9879e2e","childMarkdownRemark":{"fields":{"slug":"/getting-started"},"frontmatter":{"title":"Getting Started"}}}},{"entry":{"id":"ccfd1734-230c-5de7-8188-b9c9f36c34e9","childMarkdownRemark":{"fields":{"slug":"/installation"},"frontmatter":{"title":"Installation"}}}},{"entry":{"id":"b89feaf8-14d3-5a12-a574-31fa91dc785e","childMarkdownRemark":{"fields":{"slug":"/change-files"},"frontmatter":{"title":"Change Files"}}}},{"entry":{"id":"ed6560cb-8495-5c33-a16d-6698913b2ceb","childMarkdownRemark":{"fields":{"slug":"/ci-integration"},"frontmatter":{"title":"CI Integration"}}}}]},{"title":"CLI Reference","entries":[{"entry":{"id":"d331b943-d44c-57ee-b77c-45d0ac5a7a0d","childMarkdownRemark":{"fields":{"slug":"/change"},"frontmatter":{"title":"change"}}}},{"entry":{"id":"25b6911e-bac6-5692-80eb-8c70d1863000","childMarkdownRemark":{"fields":{"slug":"/check"},"frontmatter":{"title":"check"}}}},{"entry":{"id":"e9d2f246-5b07-5abe-92a6-d65c4c4e8ac4","childMarkdownRemark":{"fields":{"slug":"/bump"},"frontmatter":{"title":"bump"}}}},{"entry":{"id":"22b3b9a8-e74d-5bdf-83ad-d25cfbe60715","childMarkdownRemark":{"fields":{"slug":"/publish"},"frontmatter":{"title":"publish"}}}},{"entry":{"id":"55c11620-e2b0-538d-b36d-f5897681b65a","childMarkdownRemark":{"fields":{"slug":"/options"},"frontmatter":{"title":"options"}}}}]}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"/publish"}}}
+{"componentChunkName":"component---src-templates-doc-jsx","path":"/publish","webpackCompilationHash":"f24aab57cd054fc5bc5c","result":{"data":{"postBySlug":{"html":"<p>Publishing automates all the bumping and synchronizing of package versions in git remotes as well as the npm registry. The steps taken by the publish command are designed to be run so that it minimizes the chances of failure by doing validation upfront.</p>\n<p>By publishing, it'll perform the following tasks:</p>\n<ol>\n<li>Validate that there are no local changes</li>\n<li>Validate that the versions to be bumped are in fact available in the npm registry</li>\n<li>Bumps the package versions</li>\n<li>Generate package changelog files</li>\n<li>Revert all these changes</li>\n<li>Fetch latest git changes on the remote target branch</li>\n<li>Perform the exact same thing in steps 3 &#x26; 4</li>\n<li>Push these changes back to the remote target branch</li>\n</ol>\n<p>It might be surprising that <code class=\"language-text\">beachball publish</code> does so many steps, especially the step about reverting changes! In most version bumping systems that automates git repo version with npm registry, they assume that the source code is fresh by the time they push the changes back to the git repository. This is almost never the case when the build takes more than a few minutes! So, <code class=\"language-text\">beachball</code> fetches latest before we push back to the target branch. In large systems, it has been observed that without the git fetch, it becomes a source of conflict.</p>\n<p>All the options for publish are documented in the CLI <a href=\"./options\">options</a> page </p>","frontmatter":{"title":"publish"}},"tableOfContents":{"chapters":[{"title":"Overview","entries":[{"entry":{"id":"aa948e6b-0177-51ab-877c-de4df9879e2e","childMarkdownRemark":{"fields":{"slug":"/getting-started"},"frontmatter":{"title":"Getting Started"}}}},{"entry":{"id":"ccfd1734-230c-5de7-8188-b9c9f36c34e9","childMarkdownRemark":{"fields":{"slug":"/installation"},"frontmatter":{"title":"Installation"}}}},{"entry":{"id":"b89feaf8-14d3-5a12-a574-31fa91dc785e","childMarkdownRemark":{"fields":{"slug":"/change-files"},"frontmatter":{"title":"Change Files"}}}},{"entry":{"id":"ed6560cb-8495-5c33-a16d-6698913b2ceb","childMarkdownRemark":{"fields":{"slug":"/ci-integration"},"frontmatter":{"title":"CI Integration"}}}}]},{"title":"CLI Reference","entries":[{"entry":{"id":"d331b943-d44c-57ee-b77c-45d0ac5a7a0d","childMarkdownRemark":{"fields":{"slug":"/change"},"frontmatter":{"title":"change"}}}},{"entry":{"id":"25b6911e-bac6-5692-80eb-8c70d1863000","childMarkdownRemark":{"fields":{"slug":"/check"},"frontmatter":{"title":"check"}}}},{"entry":{"id":"e9d2f246-5b07-5abe-92a6-d65c4c4e8ac4","childMarkdownRemark":{"fields":{"slug":"/bump"},"frontmatter":{"title":"bump"}}}},{"entry":{"id":"22b3b9a8-e74d-5bdf-83ad-d25cfbe60715","childMarkdownRemark":{"fields":{"slug":"/publish"},"frontmatter":{"title":"publish"}}}},{"entry":{"id":"55c11620-e2b0-538d-b36d-f5897681b65a","childMarkdownRemark":{"fields":{"slug":"/options"},"frontmatter":{"title":"options"}}}}]}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"/publish"}}}

docs/sitemap.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
 <url> <loc>https://kenotron.github.io/beachball/beachball/bump</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
-<url> <loc>https://kenotron.github.io/beachball/beachball/change</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/check</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/options</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/publish</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
+<url> <loc>https://kenotron.github.io/beachball/beachball/getting-started</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/change-files</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/ci-integration</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
-<url> <loc>https://kenotron.github.io/beachball/beachball/getting-started</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/installation</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
+<url> <loc>https://kenotron.github.io/beachball/beachball/change</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 <url> <loc>https://kenotron.github.io/beachball/beachball/</loc> <changefreq>daily</changefreq> <priority>0.7</priority> </url>
 </urlset>

packages/website/content/docs/cli/publish.md

@@ -3,3 +3,20 @@ title: 'publish'
 tags: cli
 category: doc
 ---
+
+Publishing automates all the bumping and synchronizing of package versions in git remotes as well as the npm registry. The steps taken by the publish command are designed to be run so that it minimizes the chances of failure by doing validation upfront.
+
+By publishing, it'll perform the following tasks:
+
+1. Validate that there are no local changes
+2. Validate that the versions to be bumped are in fact available in the npm registry
+3. Bumps the package versions
+4. Generate package changelog files
+5. Revert all these changes
+6. Fetch latest git changes on the remote target branch
+7. Perform the exact same thing in steps 3 & 4
+8. Push these changes back to the remote target branch
+
+It might be surprising that `beachball publish` does so many steps, especially the step about reverting changes! In most version bumping systems that automates git repo version with npm registry, they assume that the source code is fresh by the time they push the changes back to the git repository. This is almost never the case when the build takes more than a few minutes! So, `beachball` fetches latest before we push back to the target branch. In large systems, it has been observed that without the git fetch, it becomes a source of conflict.
+
+All the options for publish are documented in the CLI [options](./options) page 

packages/website/content/docs/overview/ci-integration.md

@@ -3,3 +3,43 @@ title: 'CI Integration'
 tags: overview
 category: doc
 ---
+
+For the repository and package owners or admins who want to automate the bumping of versions based on change files with `beachball`, you'll need to provide some information for your Continuous Integration (CI) systems. These one-time setup steps will be unique for different CI system naturally, but the general idea remain the same. `beachball publish` needs write access to with are the git repo and npm registry.
+
+## git Repository
+
+There are several ways to authenticate against a git repository. Here's one way to do so with a personal token. Put this in your publishing build scripts:
+
+```bash
+git config user.email "someone@example.com"
+git config user.name "someone"
+git remote set-url origin https://$(user):$(pat)@github.com/someuser/someproject.git
+```
+
+> Note: never check in your credentials into a git repository! Simply use the "secret variable" feature to pass in the PAT here.
+
+These commands will give the git user a name and email. Also, the last command will set a different URL for the git remote named "origin". If you have SSH key pairs setup, you would not need to run that last line in your scripts.
+
+## npm Registry
+
+To publish to a npm registry, you'll need to have access to the write-enabled access token. npm registry has [documentation](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) on how to create write tokens. Pass this token into the command line:
+
+```beachball publish -n SOME_AUTH_TOKEN```
+
+Inside your CI scripts, it is recommended to have a `package.json` script for this:
+
+```json
+{
+  "scripts": {
+    "publish:beachball": "beachball publish -n $(npm.token)"
+  }
+}
+```
+
+Then inside the build script, simply call `yarn publish:beachball` or `npm run publish:beachball`. 
+
+A common requirement is to be able to publish to a private registry other than npmjs.org. You can also customize the registry URL by passing in one additional parameter:
+
+```
+beachball publish -n SOME_AUTH_TOKEN -r http://SOME_REGISTRY_URL/
+```