docs: udpates to project documentation

openshift · Sep 20, 2016 · 32a6a7f · 32a6a7f
1 parent 4aebd0e
commit 32a6a7f
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 91 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,25 +1,14 @@
 # How to Contribute
 
-CoreOS projects are [Apache 2.0 licensed](LICENSE) and accept contributions via
-GitHub pull requests.  This document outlines some of the conventions on
+This document outlines some of the conventions on
 development workflow, commit message formatting, contact points and other
 resources to make it easier to get your contribution accepted.
 
-# Certificate of Origin
-
-By contributing to this project you agree to the Developer Certificate of
-Origin (DCO). This document was created by the Linux Kernel community and is a
-simple statement that you, as a contributor, have the legal right to make the
-contribution. See the [DCO](DCO) file for details.
-
 # Email and Chat
 
-The project currently uses the general CoreOS email list and IRC channel:
-- Email: [coreos-dev](https://groups.google.com/forum/#!forum/coreos-dev)
-- IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) IRC channel on freenode.org
-
-Please avoid emailing maintainers found in the MAINTAINERS file directly. They
-are very busy and read the mailing lists.
+The project currently uses the general Tectonic Team email list and Slack channel:
+- Email: team-tectonic@coreos.com
+- Slack: #team-tectonic
 
 ## Getting Started
 
@@ -38,7 +27,6 @@ This is a rough outline of what a contributor's workflow looks like:
 - Make sure the tests pass, and add any new tests as appropriate.
 - Submit a pull request to the original repository.
 
-Thanks for your contributions!
 
 ### Format of the Commit Message
 

diff --git a/DCO b/DCO
diff --git a/LICENSE b/LICENSE
diff --git a/MAINTAINERS b/MAINTAINERS
@@ -1,3 +1,3 @@
 Ed Rooth <ed.rooth@coreos.com> (@sym3tri)
-Joe Bowers <joe.bowers@coreos.com> (@joeatwork)
 Matt Kaniaris <matt.kaniaris@coreos.com> (@kans)
+Lucas Serven <lucas.serven@coreos.com> (@squat)
diff --git a/README.md b/README.md
@@ -1,35 +1,37 @@
-Bridge
-======
+Tectonic Console
+================
 
-[![Build Status](https://jenkins-tectonic.prod.coreos.systems/buildStatus/icon?job=console-build)](https://jenkins-tectonic.prod.coreos.systems/job/console-build/)
+Codename: "Bridge"
 
-The Tectonic Console
+[![Build Status](https://jenkins-tectonic.prod.coreos.systems/buildStatus/icon?job=console-build)](https://jenkins-tectonic.prod.coreos.systems/job/console-build/)
 
 [quay.io/coreos/tectonic-console](https://quay.io/repository/coreos/tectonic-console?tab=tags)
 
-Bridge consists of a frontend webapp and a backend service which serves the following purposes:
+Console consists of a frontend webapp and a backend service which serves the following purposes:
 - Proxy the Kubernetes API
 - Provide additional non-Kubernetes APIs for interacting with the cluster
 - Serve all frontend static assets
-- User Authentication (TBD)
+- User Authentication
+- Some additional proxying to the Dex API
 
 ## Quickstart
 
 ### Deps:
 
-1. nodejs >= 6.0
-2. npm >= 3 (probably installed with node)
-3. go >= 1.6
+1. nodejs >= 6.0 & npm >= 3 (use of nvm is recommended)
+2. go >= 1.6
+3. [kubectl](http://kubernetes.io/docs/getting-started-guides/binary_release/#prebuilt-binary-release)
 
 ### Build everything:
+
 ```
 ./build
 ```
 
 Backend binaries are output to `/bin`.
 
 
-### Configure the application to run
+### Configure the application
 
 If you've got a working `kubectl` on your path, you can run the application with
 
@@ -55,6 +57,7 @@ kubectl describe secrets/<secret-id-obtained-previously>
 Use this token value to set the `BRIDGE_K8S_BEARER_TOKEN` environment variable when running Bridge.
 
 ## Docker
+
 The `builder-run` script will run any command from a docker container to ensure a consistent build environment.
 For example to build with docker run:
 ```
@@ -70,6 +73,9 @@ your new image. Our practice is to manually tag images builder images in the for
 `Builder-v$SEMVER` once we're happy with the state of the push.
 
 ### Compile, Build, & Push Docker Image
+
+(Almost no reason to ever do this manually, Jenkins handles this automation)
+
 Build a docker image, tag it with the current git sha, and pushes it to the `quay.io/coreos/tectonic-console` repo.
 
 Must set env vars `DOCKER_USER` and `DOCKER_PASSWORD` or have a valid `.dockercfg` file.
@@ -78,24 +84,29 @@ Must set env vars `DOCKER_USER` and `DOCKER_PASSWORD` or have a valid `.dockercf
 ```
 
 ## Hacking
-### Project Dependencies
-go, glide, nodejs, gulp
+
+See [CONTRIBUTING](CONTRIBUTING.md) for workflow & convention details.
+
+
+### Dev Dependencies
+
+go, glide, nodejs/npm, kubectl
 
 ### Frontend Development
 
+All frontend build tasks are defined in `/frontend/gulpfile.js` and are aliased to `npm run gulp`
+
 #### Install Dependencies
+
 The frontend uses node and npm to compile JS/JSX at build time. To install the build tools and dependencies:
 ```
 npm install
 ```
 
 JS is compiled into one of two bundles - one strictly for external dependencies and the other for our source.  These bundles are not commited to git.  You must run this command once, and every time the dependencies change.
-#### Build External Dependencies
-```
-npm run gulp js-deps
-```
 
 #### Interactive Development
+
 The following build task will watch the source code for changes and compile automatically.  You must reload the page!
 ```
 npm run dev
@@ -107,19 +118,8 @@ which will start both the backend server and interactive dev mode in a single pr
 goreman start
 ```
 
-#### Update Dependencies
-Dependencies should be pinned to an exact version (eg, no ^).
-
-```
-rm npm-shrinkwrap
-npm install --save the-dependency
-npm shrinkwrap
-npm run gulp js-deps
-```
-
-All frontend build tasks are defined in `/frontend/gulpfile.js` and are aliased to `npm run gulp`
-
 ### Tests
+
 Run all tests:
 ```
 ./test
@@ -136,16 +136,34 @@ Run frontend tests:
 ```
 
 ### Dependency Management
-Add new frontend dependencies:
- 1. `npm install --save` the dependency
- 2. commit the altered `package.json`
+
+Dependencies should be pinned to an exact semver, sha, or git tag (eg, no ^).
+
+#### Backend
 
 Add new backend dependencies:
- 1. Edit glide.yaml
+ 1. Edit `glide.yaml`
  2. `glide update -s -v -u`
 
-### API Schema
-If changes are made to the `schema/v1.json` file you must regenerate the go bindings:
+Update existing backend dependencies:
+ 1. Edit the `glide.yaml` file to the desired verison (most likely a git hash)
+ 2. Run `glide update -u github.com/$ORG/$REPO`
+ 3. Verify update was successful. `glide.lock` will have been updated to reflect the changes to `glide.yaml` and the package will have been updated in `vendor`.
+
+#### Frontend
+
+Add new frontend dependencies:
+```
+rm npm-shrinkwrap
+npm install --save the-dependency
+npm shrinkwrap
+npm run gulp js-deps
+```
+
+Update existing frontend dependencies:
 ```
-./schema/generator
+rm npm-shrinkwrap
+npm install --save the-dependency
+npm shrinkwrap
+npm run gulp js-deps
 ```