diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2f9579f5..0e16c6c28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,3 +85,46 @@ following steps in order to be able to compile and test Packer. 7. If everything works well and the tests pass, run `go fmt` on your code before submitting a pull-request. + +### Tips for Working on Packer + +#### Godeps + +If you are submitting a change that requires a change in dependencies, DO NOT update the `vendor/` folder. This keeps the PR smaller and easier to review. Instead, please indicate which upstream has changed and which version we should be using. You _may_ do this using `Godeps/Godeps.json` but this is not required. + +#### Running Unit Tests + +You can run tests for individual packages using commands like this: + + $ make test TEST=./builder/amazon/... + +#### Running Acceptance Tests + +Packer has [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing) +for various builders. These typically require an API key (AWS, GCE), or +additional software to be installed on your computer (VirtualBox, VMware). + +If you're working on a feature of a builder or a new builder and want verify it +is functioning (and also hasn't broken anything else), we recommend running the +acceptance tests. + +**Warning:** The acceptance tests create/destroy/modify *real resources*, which +may incur real costs in some cases. In the presence of a bug, it is technically +possible that broken backends could leave dangling data behind. Therefore, +please run the acceptance tests at your own risk. At the very least, we +recommend running them in their own private account for whatever builder you're +testing. + +To run the acceptance tests, invoke `make testacc`: + + $ make testacc TEST=./builder/amazon/ebs + ... + +The `TEST` variable lets you narrow the scope of the acceptance tests to a +specific package / folder. The `TESTARGS` variable is recommended to filter +down to a specific resource to test, since testing all of them at once can +sometimes take a very long time. + +Acceptance tests typically require other environment variables to be set for +things such as access keys. The test itself should error early and tell you +what to set, so it is not documented here. \ No newline at end of file diff --git a/README.md b/README.md index 7285fe6d4..55e8cd87d 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,9 @@ Packer is a tool for building identical machine images for multiple platforms from a single source configuration. Packer is lightweight, runs on every major operating system, and is highly -performant, creating machine images for multiple platforms in parallel. -Packer comes out of the box with support for the following platforms: +performant, creating machine images for multiple platforms in parallel. Packer +comes out of the box with support for the following platforms: + * Amazon EC2 (AMI). Both EBS-backed and instance-store AMIs * DigitalOcean * Docker @@ -79,87 +80,10 @@ they're run, etc. is up to you. ## Documentation -Full, comprehensive documentation is viewable on the Packer website: +Comprehensive documentation is viewable on the Packer website: http://www.packer.io/docs ## Developing Packer -If you wish to work on Packer itself or any of its built-in providers, -you'll first need [Go](http://www.golang.org) installed (version 1.4+ is -_required_). Make sure Go is properly installed, including setting up -a [GOPATH](http://golang.org/doc/code.html#GOPATH). - -Next, install the following software packages, which are needed for some dependencies: - -- [Bazaar](http://bazaar.canonical.com/en/) -- [Git](http://git-scm.com/) -- [Mercurial](http://mercurial.selenic.com/) - -Then, install [Gox](https://github.com/mitchellh/gox), which is used -as a compilation tool on top of Go: - - $ go get -u github.com/mitchellh/gox - -Next, clone this repository into `$GOPATH/src/github.com/mitchellh/packer`: - - $ cd $GOPATH/src/github.com/mitchellh - $ git clone https://github.com/mitchellh/packer.git - $ cd packer - -Install the necessary dependencies by running `make updatedeps` and then just -type `make`. This will compile some more dependencies and then run the tests. If -this exits with exit status 0, then everything is working! - - $ make updatedeps - ... - $ make - ... - -To compile a development version of Packer and the built-in plugins, -run `make dev`. This will put Packer binaries in the `bin` folder: - - $ make dev - ... - $ bin/packer - ... - - -If you're developing a specific package, you can run tests for just that -package by specifying the `TEST` variable. For example below, only -`packer` package tests will be run. - - $ make test TEST=./packer - ... - -### Acceptance Tests - -Packer has comprehensive [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing) -covering the builders of Packer. - -If you're working on a feature of a builder or a new builder and want -verify it is functioning (and also hasn't broken anything else), we recommend -running the acceptance tests. - -**Warning:** The acceptance tests create/destroy/modify *real resources*, which -may incur real costs in some cases. In the presence of a bug, it is technically -possible that broken backends could leave dangling data behind. Therefore, -please run the acceptance tests at your own risk. At the very least, -we recommend running them in their own private account for whatever builder -you're testing. - -To run the acceptance tests, invoke `make testacc`: - -```sh -$ make testacc TEST=./builder/amazon/ebs -... -``` - -The `TEST` variable is required, and you should specify the folder where the -backend is. The `TESTARGS` variable is recommended to filter down to a specific -resource to test, since testing all of them at once can sometimes take a very -long time. - -Acceptance tests typically require other environment variables to be set for -things such as access keys. The test itself should error early and tell -you what to set, so it is not documented here. +See [CONTRIBUTING.md](https://github.com/mitchellh/packer/blob/master/CONTRIBUTING.md) for best practices and instructions on setting up your development environment to work on Packer.