README and CONTRIBUTING documentation (#199)

This commit is contained in:
Mike Arpaia 2016-09-20 10:32:00 -07:00 committed by GitHub
parent 973ef9dbd1
commit 9ba53333fd
2 changed files with 213 additions and 34 deletions

81
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,81 @@
## Filing issues
When filing an issue, make sure to answer these five questions:
1. What version of Kolide are you using (`kolide version --full`)?
2. What operating system are you using?
3. What did you do?
4. What did you expect to happen?
5. What happened instead?
Sensitive security-related issues should be reported to
[security@kolide.co](mailto:security@kolide.co) before a public issue is made.
## Code of Conduct
### Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of
experience, nationality, personal appearance, race, religion, or sexual identity
and orientation.
### Our Standards
Examples of behavior that contributes to creating a positive environment
include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
### Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening,
offensive, or harmful.
### Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
### Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at hello@kolide.co. All complaints will
be reviewed and investigated and will result in a response that is deemed
necessary and appropriate to the circumstances. The project team is obligated to
maintain confidentiality with regard to the reporter of an incident. Further
details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
### Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
available at http://contributor-covenant.org/version/1/4.

166
README.md
View File

@ -6,18 +6,26 @@
- [Installing build dependencies](#installing-build-dependencies)
- [Building](#building)
- [Generating the packaged JavaScript](#generating-the-packaged-javascript)
- [Compiling the kolide binary](#compiling-the-kolide-binary)
- [Automatic rebuilding of the JavaScript bundle](#automatic-rebuilding-of-the-javascript-bundle)
- [Compiling the Kolide binary](#compiling-the-kolide-binary)
- [Managing Go dependencies with glide](#managing-go-dependencies-with-glide)
- [Automatic recompilation](#automatic-recompilation)
- [Testing](#testing)
- [Application tests](#application-tests)
- [Full test suite](#full-test-suite)
- [Go unit tests](#go-unit-tests)
- [JavaScript unit tests](#javascript-unit-tests)
- [Go linters](#go-linters)
- [JavaScript linters](#javascript-linters)
- [Viewing test coverage](#viewing-test-coverage)
- [Testing email](#testing-email)
- [Email](#email)
- [Testing email using MailHog](#testing-email-using-mailhog)
- [Viewing email content in the terminal](#viewing-email-content-in-the-terminal)
- [Development Infrastructure](#development-infrastructure)
- [Starting the local development environment](#starting-the-local-development-environment)
- [Stopping the local development environment](#stopping-the-local-development-environment)
- [Setting up the database tables](#setting-up-the-database-tables)
- [Running Kolide](#running-kolide)
- [Using Docker development infrastructure](#using-docker-development-infrastructure)
- [Using no external dependencies](#using-no-external-dependencies)
## Development Environment
@ -27,17 +35,28 @@
To setup a working local development environment, you must install the following
minimum toolset:
* [Docker](https://www.docker.com/products/overview#/install_the_platform)
* [Go](https://golang.org/dl/) (1.6 or greater)
* [Go](https://golang.org/dl/) (1.7 or greater)
* [Node.js](https://nodejs.org/en/download/current/) (and npm)
* [GNU Make](https://www.gnu.org/software/make/)
* [Docker](https://www.docker.com/products/overview#/install_the_platform)
Once you have those minimum requirements, to install build dependencies, run the following:
If you're using MacOS or Linux, you should have Make installed already. If you
are using Windows, you will need to install it separately. Additionally, if you
would only like to run an in-memory instances of Kolide (for demonstrations,
testing, etc.), then you do not need to install Docker.
Once you have those minimum requirements, you will need to install Kolide's
dependent libraries. To do this, run the following:
```
make deps
```
When pulling in new revisions to the Kolide codebase to your working source
tree, it may be necessary to re-run `make deps` if a new Go or JavaScript
dependency was added.
### Building
#### Generating the packaged JavaScript
@ -49,7 +68,39 @@ following:
make generate
```
#### Compiling the kolide binary
#### Automatic rebuilding of the JavaScript bundle
Normally, `make generate` takes the JavaScript code, bundles it into a single
bundle via Webpack, and inlines that bundle into a generated Go source file so
that all of the frontend code can be statically compiled into the binary. When
you build the code after running `make generate`, all of that JavaScript is
included in the binary.
This makes deploying Kolide a dream, since you only have to worry about a single
static binary. If you are working on frontend code, it is likely that you don't
want to have to manually re-run `make generate` and `make build` every time you
edit JavaScript and CSS in order to see your changes in the browser. To solve
this problem, before you build the Kolide binary, run the following command
instead of `make generate`:
```
make generate-dev
```
Instead of reading the JavaScript from a inlined static bundle compiled within
the binary, `make generate-dev` will generate a Go source file which reads the
frontend code from disk and run Webpack in "watch mode".
Note that when you run `make generate-dev`, Webpack will be watching the
JavaScript files that were used to generate the bundle, so the process will be
long lived. Depending on your personal workflow, you might want to run this in a
background terminal window.
After you run `make generate-dev`, run `make build` to build the binary, launch
the binary and you'll be able to refresh the browser whenever you edit and save
frontend code.
#### Compiling the Kolide binary
Use `go build` to build the application code. For your convenience, a make
command is included which builds the code:
@ -88,25 +139,54 @@ To update, use [`glide up`](https://github.com/Masterminds/glide#glide-update-al
### Testing
#### Application tests
#### Full test suite
You can use [`go test $(glide novendor)`](https://github.com/Masterminds/glide#glide-novendor-aliased-to-nv)
to run the go unit tests and skip tests in the vendor directory. This will run
go test over all directories of your project except the vendor directory.
To execute all of the tests that CI will execute, run the following from the root
of the repository:
To execute all of the tests that CI will execute, run the following from the
root of the repository:
```
make test
```
It is a good idea to run `make test` before submitting a Pull Request.
#### Go unit tests
To run all Go unit tests, run the following:
```
make test-go
```
#### JavaScript unit tests
To run all JavaScript unit tests, run the following:
```
make test-js
```
#### Go linters
To run all Go linters and static analyzers, run the following:
```
make lint-go
```
#### JavaScript linters
To run all JavaScript linters and static analyzers, run the following:
```
make lint-js
```
#### Viewing test coverage
When you run `make test` from the root of the repository, test coverage reports
are generated in every subpackage. For example, the `sessions` subpackage will
have a coverage report generated in `./sessions/sessions.cover`
When you run `make test` or `make test-go` from the root of the repository, test
coverage reports are generated in every subpackage. For example, the `server`
subpackage will have a coverage report generated in `./server/server.cover`
To explore a test coverage report on a line-by-line basis in the browser, run
the following:
@ -123,7 +203,9 @@ To view test a test coverage report in a terminal, run the following:
go tool cover -func=./server/server.cover
```
#### Testing Email
### Email
#### Testing email using MailHog
To intercept sent emails while running a Kolide development environment, make
sure that you've set the SMTP address to `<docker host ip>:1025` and leave the
@ -133,15 +215,17 @@ browser to view the [MailHog](https://github.com/mailhog/MailHog) UI.
For example, if docker is running natively on your `localhost`, then your mail
settings should look something like:
```json
{
"mail": {
"address": "localhost:1025",
"pool_connections": 4
}
}
```yaml
mail:
address: localhost:1025
```
#### Viewing email content in the terminal
If you're [running Kolide in dev mode](#using-no-external-dependencies), emails
will be printed to the terminal instead of being sent via an SMTP server. This
may be useful if you want to view the content of all emails that Kolide sends.
### Development infrastructure
#### Starting the local development environment
@ -177,17 +261,31 @@ kolide prepare db
### Running Kolide
Now you are prepared to run a Kolide development environment. Run the following:
#### Using Docker development infrastructure
To start the Kolide server backed by the Docker development infrasturcture, run
the Kolide binary as follows:
```
kolide serve
```
If you're running the binary from the root of the repository, where it is built
by default, then the binary will automatically use the provided example
configuration file, which assumes that you are running docker locally, on
`localhost` via a native engine.
There is an example configuration file included in this repository to make this
process easier for you. You may have to edit the example configuration file to
use the output of `docker-machine ip` instead of `localhost` if you're using
Docker via [Docker Toolbox](https://www.docker.com/products/docker-toolbox).
You may have to edit the example configuration file to use the output of
`docker-machine ip` instead of `localhost` if you're using Docker via
[Docker Toolbox](https://www.docker.com/products/docker-toolbox).
#### Using no external dependencies
If you'd like to launch the Kolide server with no external dependencies, run
the following:
```
kolide serve --dev
```
This will use in-memory mocks for the database, print emails to the console,
etc. If you're demo-ing Kolide or testing a quick feature, dev mode is ideal.
Keep in mind that, since everything is in-memory, when you kill the process,
everything you did in dev mode will be lost. This is nice for development but
not so nice for production environments.