For Developer

Overview

Most of development work can be done without a gocd development environment. We have a "real" gocd server implemented in golang, so you can implement all features basing on this server, checkout agent/build_session_test.go for how to implement a feature test.
After checkout codebase, run ./build.sh to install dependent packages.
You can start with exploring main.go and agent/agent.go for understanding how agent works.
For integration test with latest changes, you need checkout https://github.com/gocd/gocd, please see gocd readme for details of setup development environment. No special configuration needed, launch gocd development server is enough for integration.
You can also download latest GoCD installer for integration test if changes were not related to latest protocol changes. There is no specific configuration needed.

agent: main package
- Initialize agent: agent/config.go maintains all configurations that is going through environment variables
- Register agent on server, and communicate with server by Websocket.
- Process BuildCommand from server.
protocol: this package defines all BuildCommand and agent server communication protocols details, including constants, helper methods, and structs shared between server and agent implementation. It does not contain any real logic of how to process any message or command sent from server.
server: this package implements a "real" Go server supporting BuildCommand protocol. Notice it's not a mock or stub server. It handles everything for behaving as a Go server. Agent package is using this server for testing BuildCommand protocol implementation.
installers: all installer related stuff should be in here.
other packages: util packages, no Go agent related logic, and all used by agent or server packages.

BuildCommand protocol original proposal: https://github.com/gocd/gocd/issues/1954
BuildCommand protocol Go server side implementation PR: https://github.com/gocd/gocd/pull/2052
agent/build_session.go implements processor and setting up all runtime context.
type Executor func(session *BuildSession, cmd *protocol.BuildCommand) error defines a BuildCommand executor for processing a specific BuildCommand.
Each build command executor is a standalone file in agent package prefixed with command, for example: command_echo executes echo command. (Note: test command is in agent/test.go, because a file named command_test.go will be considered as test file and excluded from agent package. :)
func Executors() map[string]Executor defined in build_session.go hooks up command executors with BuildSession BuildCommand processor.
agent/artifacts.go handles upload & download in http level.
agent/build_console.go handles caching and flushing console log to server periodically.

Unless it's an util method or package, all agent logic related tests should be an end to end test using our test server.
All test helper methods are defined in agent/agent_test.go including func TestMain
There are setUp(t *testing.T) and tearDown() methods for re-initializing an agent and quit the testing agent.
All tests will share one single server. Server was started in func TestMain. After server started, TestMain will setup agent configuration by setting up environment variables.
All tests running independently by using different buildId which is generated from test name in setUp
Agent and server logs can be found in test working directory printed when test started.

Set environment variable DEBUG to any value will turn on debug log
By default agent log will output to stdout.
For removing possibilities of leaking user's credentials or other confidential info, DO NOT log entire BuildCommand struct data, even in debug log.