Merge pull request #47 from ngrok/ror/readme

feat: updating readme

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to ngrok-go
+
+Thank you for deciding to contribute to ngrok-go!
+
+## Reporting a bug
+
+To report a bug, please [open a new issue](https://github.com/ngrok/ngrok-go/issues/new) with clear reproduction steps. We will triage and investigate these issues at a regular interval.
+
+## Contributing code
+
+Bugfixes and small improvements are always appreciated!
+
+For any larger changes or features, please [open a new issue](https://github.com/ngrok/ngrok-go/issues/new) first to discuss whether the change makes sense. When in doubt, it's always okay to open an issue first.
+
+## Building and running tests
+
+The library can be compiled with `go build`.
+
+To run tests, `go test`.
+
+Tests are split into a number of categories that can be enabled as desired via environment variables. By default, only offline tests run which validate tunnel protocol RPC messages generated from the `config` APIs. The other tests are gated behind the following environment variables:
+
+* `NGROK_TEST_ONLINE`: All online tests require this variable to be set
+* `NGROK_TEST_AUTHED`: Enables tests that require an ngrok account and that the authtoken is set in `NGROK_AUTHTOKEN`.
+* `NGROK_TEST_PAID`: Enables online, authenticated tests that require access to paid features. If your subscription doesn't support a feature being tested, you should see error messages to that effect.
+* `NGROK_TEST_LONG`: Enables online tests that may take longer than most. May also require the `AUTHED` and/or `PAID` groups enabled.
+* `NGROK_TEST_FLAKEY`: Enable online tests that may be unreliable. Their success or failure may depend on network conditions, timing, solar flares, ghosts in the machine, etc.
+
+This list may be incomplete and drift slightly as we add more tests and granularity. See the tests in `online_test.go` for the most accurate list.

README.md

@@ -1,11 +1,74 @@
+[![Go Reference](https://pkg.go.dev/badge/golang.ngrok.com/ngrok.svg)](https://pkg.go.dev/golang.ngrok.com/ngrok)
+[![Go](https://github.com/ngrok/ngrok-go/actions/workflows/buildandtest.yml/badge.svg)](https://github.com/ngrok/ngrok-go/actions/workflows/buildandtest.yml)
 # ngrok-go
 
-**Note: This is alpha-quality software. Interfaces are subject to change
-without warning**
+ngrok is a globally distributed reverse proxy commonly used for quickly getting a public URL to a service running inside a private network, such as on your local laptop. The ngrok agent is usually deployed inside a private network and is used to communicate with the ngrok cloud service.
 
-This is the ngrok agent in library form, suitable for integrating directly into
-an application. See `example/http.go` for example usage, or the tests in
-`online_test.go`.
+This is the ngrok agent in library form, suitable for integrating directly into Go applications. This allows you to quickly build ngrok into your application with no separate process to manage. 
+
+See [`examples/http/main.go`](/examples/http/main.go) for example usage, or the tests in [`online_test.go`](/online_test.go).
+
+## Installation
+
+The best way to install the ngrok agent SDK is through `go get`.
+
+```sh
+go get golang.ngrok.com/ngrok
+```
+## Documentation
+A full API reference is included in the [ngrok go sdk documentation on pkg.go.dev](https://pkg.go.dev/golang.ngrok.com/ngrok). Check out the [ngrok Documentation](https://ngrok.com/docs) for more information about what you can do with ngrok.
+## Quickstart
+For more examples of using ngrok-go, check out the [/examples](/examples) folder.
+
+The following example uses ngrok to start an http endpoint with a random url that will route traffic to the handler. The ngrok URL provided when running this example is accessible by anyone with an internet connection.
+
+The ngrok authtoken is pulled from the `NGROK_AUTHTOKEN` environment variable. You can find your authtoken by logging into the [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).
+
+You can run this example with the following command:
+```sh
+NGROK_AUTHTOKEN=xxxx_xxxx go run examples/http/main.go
+```
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+
+	"golang.ngrok.com/ngrok"
+	"golang.ngrok.com/ngrok/config"
+)
+
+func main() {
+	if err := run(context.Background()); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run(ctx context.Context) error {
+	tun, err := ngrok.StartTunnel(ctx,
+		config.HTTPEndpoint(),
+		ngrok.WithAuthtokenFromEnv(),
+	)
+	if err != nil {
+		return err
+	}
+
+	log.Println("tunnel created:", tun.URL())
+
+	return http.Serve(tun, http.HandlerFunc(handler))
+}
+
+func handler(w http.ResponseWriter, r *http.Request) {
+	fmt.Fprintln(w, "Hello from ngrok-go!")
+}
+```
+
+## Support
+The best place to get support using ngrok-go is through the [ngrok Slack Community](https://ngrok.com/slack). If you find bugs or would like to contribute code, please follow the instructions in the [contributing guide](/CONTRIBUTING.md).
 
 ## License