docs: add a developing.md (#1752)

Add a `DEVELOPING.md` capturing some basic instructions on how to develop in this repository, including instructions on how to use Modules to add, update and remove dependencies.

To make a clear path for folks to add, update and remove dependencies. While we mostly use the standard Go modules features to manage dependencies they are relatively new in the ecosystem and it is helpful if we anyone adding dependencies knows how to get it right first time without needing to iterate, receive CI or PR feedback, and then do more work.

We also use a non-standard [go.list](go.list) file so that we can see what our actual build/tested dependency versions are in PR diffs, according to `go list -m all`.

CI will error if any steps haven't been followed for updating dependencies, but as @graydon pointed out when he was our first person doing an upgrade, it's helpful if we can give developers clear instructions so they have the opportunity to get it right and so it's not an unknown they're stepping into.

It's worth addressing that there is some overlap of these instructional files, e.g. `README.md`, `DEVELOPING.md` and `CONTRIBUTING.md`, but each has a different target audience and are relevant at different stages.

- `README.md`: Folks learning about our code, importing the Go SDK, installing from source.
- `DEVELOPING.md`: Developers wanting to make changes to the code.
- `CONTRIBUTING.md`: Developers wanting to contribute changes back to this repo.

For this reason it would be overwhelming to dump all this information into `README.md`, or to clutter `CONTRIBUTING.md` with details that are no longer relevant to a developer when they are thinking about opening a PR.

This is a follow up to #1634.

DEVELOPING.md

@@ -0,0 +1,98 @@
+# Developing
+
+Welcome to the Stellar Go monorepo. These instructions help launch 🚀 you into making and testing code changes to this repository. If you're aiming to submit a contribution make sure to also read the [contributing guidelines](CONTRIBUTING.md).
+
+For details about what's in this repository and how it is organized read the [README.md](README.md).
+
+## Requirements
+To checkout, build, and run most tests these tools are required:
+- Git
+- [Go 1.12 or Go 1.13](https://golang.org/dl)
+
+To run some tests these tools are also required:
+- PostgreSQL 9.6+ server running locally, or set [environment variables](https://www.postgresql.org/docs/9.6/libpq-envars.html) (e.g. `PGHOST`, etc) for alternative host.
+- MySQL 10.1+ server running locally.
+- Redis 5.0+ server running on localhost port 6379.
+
+## Get the code
+
+Check the code out anywhere, using a `GOPATH` is not required.
+
+```
+git clone https://github.com/stellar/go
+```
+
+Note: If you're using Go 1.12 and you checkout to a path inside your `GOPATH` you'll need to set the environment variable `GO111MODULE=on` for [modules](https://github.com/golang/go/wiki/Modules) dependency management to function.
+
+## Installing dependencies
+
+Dependencies are managed using [Modules](https://github.com/golang/go/wiki/Modules). Dependencies for the packages you are building will be installed automatically when running any Go command that requires them. If you need to pre-download all dependencies for the repository for offline development, run `go mod download`.
+
+See [Dependency management](#dependency-management) for more details.
+
+## Running tests
+
+```
+go test ./...
+```
+
+## Running services/tools
+
+```
+go run ./services/<service>
+```
+
+```
+go run ./tools/<tool>
+```
+
+## Dependency management
+
+Dependencies are managed using [Modules](https://github.com/golang/go/wiki/Modules) and are tracked in the repository across three files:
+- [go.mod](go.mod): Contains a list of direct dependencies, and some indirect dependencies (see [why](https://github.com/golang/go/wiki/Modules#why-does-go-mod-tidy-record-indirect-and-test-dependencies-in-my-gomod)).
+- [go.sum](go.sum): Contains hashes for dependencies that are used for verifying downloaded dependencies.
+- [go.list](go.list): A file that is unique to this Go repository, containing the output of `go list -m all`, and captures all direct and indirect dependencies and their versions used in builds and tests within this repository. This is not a lock file but instead it helps us track over time which versions are being used for builds and tests, and to see when that changes in PR diffs.
+
+### Adding new dependencies
+
+Add new dependencies by adding the import paths to the code. The next time you execute a Go command the tool will update the `go.mod` and `go.sum` files.
+
+To add a specific version of a dependency use `go get`:
+
+```
+go get <importpath>@<version>
+```
+
+Go modules files track the minimum dependency required, not the exact dependency version that will be used. To validate the version of the dependency being used update the `go.list` file by running `go mod -m all > go.list`.
+
+Before opening a PR make sure to run these commands to tidy the module files:
+- `go mod tidy`
+- `go list -m all > go.list`
+
+### Updating a dependency
+
+Update an existing dependency by using `go get`:
+
+```
+go get <importpath>@<version>
+```
+
+Go modules files track the minimum dependency required, not the exact dependency version that will be used. To validate the version of the dependency being used update the `go.list` file by running `go mod -m all > go.list`.
+
+Before opening a PR make sure to run these commands to tidy the module files:
+```
+go mod tidy
+go list -m all > go.list
+```
+
+### Removing a dependency
+
+Remove a dependency by removing all import paths from the code, then use the following commands to remove any unneeded direct or indirect dependencies:
+
+```
+go mod tidy
+go list -m all > go.list
+```
+
+Note: `go list -m all` may show that the dependency is still being used. It will be possible that the dependency is still an indirect dependency. If it's important to understand why the dependency is still being used, use `go mod why <importpath>/...` and `go mod graph | grep <importpath>` to understand which modules are importing it.
+

README.md

@@ -68,3 +68,7 @@ Often, we provide test packages that aid in the creation of tests that interact
 ### Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+### Developing
+
+See [DEVELOPING.md](DEVELOPING.md) for helpful instructions for getting started developing code in this repository.