Merge pull request #99 from technosophos/fix/release-process-docs

Updated a bunch of things related to WAGI releases

LICENSE.txt

@@ -17,4 +17,5 @@ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,6 @@
 # WAGI: WebAssembly Gateway Interface
 
-_WAGI is the easiest way to get started doing cloud-side WebAssembly apps._
+_WAGI is the easiest way to get started writing WebAssembly microservices and web apps._
 
 **WARNING:** This is experimental code.
 It is not considered production-grade by its developers, neither is it "supported" software.
@@ -22,11 +22,20 @@ You can use any programming language that can compile to `WASM32-WASI`.
 
 Here's the fastest way to try out WAGI.
 For details, checkout out the [documentation](docs/README.md).
-You will need a Rust environment to build Wagi.
 
-To run the WAGI server, use `make run`. This will start WAGI on `http://localhost:3000`.
+1. Get the [latest binary release](https://github.com/deislabs/wagi/releases)
+2. Unpack it `tar -zxf wagi-VERSION-OS.tar.gz`
+3. Run the `wagi --help` command
 
-Use a browser or a tool like `curl` to test:
+If you would like to try out a few simple configurations, we recommend cloning this repository
+and then using the `examples` directory:
+
+```console
+$ wagi -c examples/modules.toml
+No log_dir specified, using temporary directory /var/folders/hk/l1mlxz1x01x9yl33ll9vh9980000gp/T/.tmpx55XkJ for logs
+```
+
+This will start WAGI on `http://localhost:3000`. Use a browser or a tool like `curl` to test:
 
 ```
 $ curl -v http://localhost:3000/hello/world
@@ -57,10 +66,9 @@ Wagi is an implementation of CGI for WebAssembly.
 That means that writing a Wagi module is as easy as sending properly formatted content to standard output.
 If you want to understand the details, read the [Common Gateway Interface 1.1](https://tools.ietf.org/html/rfc3875) specification.
 
-- [env_wagi](https://github.com/deislabs/env_wagi): Dump the environment that WAGI sets up, including env vars and args.
-- [hello-wagi-grain](https://github.com/deislabs/hello-wagi-grain): An easy-to-read Grain example for WAGI.
-- [hello-wagi-as](https://github.com/deislabs/hello-wagi-as): AssemblyScript example using environment variables and query params.
-- [Wagi Fileserver](https://github.com/deislabs/wagi-fileserver): A fileserver written in Grain, compiled to Wasm, and ready to run in Wagi.
+Take a look at the [Wagi Examples Repository](https://github.com/deislabs/wagi-examples) for examples in various languages.
+
+For a "production grade" (whatever that means for a pre-release project) module, checkout out the [Wagi Fileserver](https://github.com/deislabs/wagi-fileserver): A fileserver written in Grain, compiled to Wasm, and ready to run in Wagi.
 
 ## Contributing
 

docs/README.md

@@ -6,4 +6,5 @@ WAGI is a system for building HTTP services with simple WASM+WASI modules. No ex
 - [Configuring and Running WAGI](configuring_and_running.md)
 - [Writing WAGI Modules](writing_modules.md)
 - [Environment Variable Reference](environment_variables.md)
-- [Architectural Overview](architecture.md)
+- [Architectural Overview](architecture.md)
+- [Release Guide](release-process.md)

docs/installation.md

@@ -1,8 +1,29 @@
 # Installing the WAGI Server
 
-Currently there are no prebuilt binaries of WAGI. You will need to build your own.
+## Prebuilt Binaries
 
-## Prerequisites
+To get started with a binary release, head to the [releases page](https://github.com/deislabs/wagi/releases)
+and download the desired release. Usually, the most recent release is the one you want.
+
+You can generate and compare the SHA with `shasum`:
+
+```console
+$ shasum wagi-v0.2.0-linux-amd64.tar.gz
+ad4114b2ed9e510a8c24348d5ea544da55c685f5  wagi-v0.2.0-linux-amd64.tar.gz
+```
+
+You can then compare that SHA with the one present in the release notes.
+
+Unpack the `.tar.gz`. The `wagi` file is the binary server.
+You may wish to put it on your `PATH` at a location such as `/usr/local/bin`.
+But that is up to you.
+On some systems, you may need to set the execute bit (`chmod 755 wagi`).
+
+From there, you can run `wagi` directly. We recommend starting with `wagi --help`.
+
+The rest of this document deals with building and running Wagi from source.
+
+## Prerequisites for Working With Source
 
 - Rust (a recent version. We suggest 1.52 or later)
 - A Linux/macOS/UNIX/WSL2/Windows environment
@@ -13,7 +34,7 @@ encounter any issues.
 
 > On Windows, you may prefer to use `just` instead of `make` to run the `Makefile` commands.
 
-## Building
+## Building from Source
 
 To build a static binary, run the following command:
 

docs/release-process.md

@@ -0,0 +1,17 @@
+# Cutting a Wagi Release
+
+To cut a release of Wagi, you will need to do the following:
+
+1. Create a pull request that changes the version number for your new version (e.g. 1.2.2 becomes 1.2.3)
+    - `Cargo.toml` is the most important place to make this change
+    - Check the docs for hard-coded version strings
+2. Merge the PR created in #1 (Such PRs are still required to get approvals, so make sure you get signoff on the PR)
+3. Create a new tag with a `v` and then the version number (`v1.2.3`)
+4. Push the tag up to `main` on GitHub
+    - This will trigger a release build
+5. Wait for the `release` [action](https://github.com/deislabs/wagi/actions/workflows/release.yaml) to complete, and download the binary artifacts that are generated by that action.
+6. Generate SHAs of the Windows, Mac, and Linux binaries with `shasum` or a similar command
+7. Go to the GitHub [tags page](https://github.com/deislabs/wagi/releases) and create a release, adding release notes, and uploading the binaries you downloaded above. The SHAs should go in the release notes.
+
+
+At this point, you can just verify that all things are good.

src/main.rs

@@ -37,7 +37,7 @@ pub async fn main() -> Result<(), anyhow::Error> {
         .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
         .init();
     let matches = App::new("WAGI Server")
-        .version("0.2.0")
+        .version(clap::crate_version!())
         .author("DeisLabs")
         .about(ABOUT)
         .arg(