Rewrite README to focus on benefits and push build instructions to CO…

…NTRIBUTING.md
addyess · Sep 2, 2019 · 7935d90 · 7935d90
1 parent aabdea9
commit 7935d90
Show file tree

Hide file tree

Showing 2 changed files with 111 additions and 45 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,11 +1,15 @@
+Thanks for your interest in Juju! Contributions like yours make good projects
+great.
+
 Contents
 ========
 
-1. [Getting started](#getting-started)
-2. [Dependency management](#dependency-management)
-3. [Code formatting](#code-formatting)
-4. [Workflow](#workflow)
-5. [Community](#community)
+1. [Building Juju](#building-juju)
+2. [Getting started](#getting-started)
+3. [Dependency management](#dependency-management)
+4. [Code formatting](#code-formatting)
+5. [Workflow](#workflow)
+6. [Community](#community)
 
 Quick links
 ===========
@@ -21,27 +25,71 @@ Community:
 * https://discourse.jujucharms.com/
 * [#juju on freenode](http://webchat.freenode.net/?channels=juju)
 
-Getting started
-===============
+Building Juju
+=============
 
-Thanks for your interest in Juju! Contributions like yours make good projects
-great. Before contributing please read the following sections describing the
-tools and conventions of this project. This file is a companion to
-[README](README.md) and it is assumed that file has been read and followed
-prior.
+## Installing Go
 
-Specifically, the following commands should already have been run:
+`juju` is written in Go (http://golang.org), a modern, compiled, statically typed,
+concurrent language.
 
-```bash
-go get -d -v github.com/juju/juju/...
-cd $GOPATH/src/github.com/juju/juju
-make install-dependencies
-```
+### via snap
+
+    snap install go --channel=1.12/stable --classic
+
+### via apt
+
+    sudo add-apt-repository ppa:gophers/archive
+    sudo apt update
+    sudo apt install go-lang-1.12
+
+### Other options
+
+See https://golang.org/doc/install#install
+
+## Set up environment variables
+
+Your `GOPATH`  is where the `go` tool and your IDE find Go source code (`$GOPATH/src`), executables (`$GOPATH/bin`) and packages (`$GOPATH/pkg`). Adding `GOPATH` to your `PATH` enables you to run Go programs that you install.
+
+    export GOPATH=${HOME}/go
+    export PATH="$GOPATH/bin/:$PATH"
+
+You should also make sure that the `$GOPATH` directory exists: 
+
+    mkdir -p $GOPATH
+
+## Build Juju and its dependencies
+
+### Download Juju source
+
+    go get -d -v github.com/juju/juju/...
 
 The `-d` option means the source (for Juju and its dependencies) is only
-downloaded and not built. This is required since the dependencies may be out
-of sync and fail to build properly. See the
-[Dependency management](#dependency-management) section for more information.
+downloaded, but not built. We need to install the dependencies ourselves with `dep`.
+
+### Change to the Juju source code directory  
+
+    cd $GOPATH/src/github.com/juju/juju
+
+### Install runtime dependencies
+
+    make install-dependencies
+
+### Install build dependencies
+
+    go get github.com/golang/dep
+    make dep
+
+`dep` is the tool that the Juju team uses to manage its dependencies.
+See the [Dependency management](#dependency-management) section for details.
+
+### Compile
+
+    make build
+
+### Install
+
+    make install
 
 Git
 ---

diff --git a/README.md b/README.md
@@ -1,41 +1,59 @@
 [![Juju logo](doc/juju-logo.png?raw=true)](https://jujucharms.com/)
 
+Simple, secure and stable devops tooling. 
+Juju keeps complexity low and productivity high. 
+Built to manage today’s complex application architectures wherever they are run.
+
+Built for
+- SRE and operations teams
+- Developers
+- Data engineers
+
+Excels at
+- Making your deployment understandable 
+- Simplifying post-install operations, such as upgrades, updates and configuration management
+- Managing hybrid-cloud services, whether on Kubernetes, VMs, bare metal or any combination
+
 ## Why Juju?
 
-* Reduce complexity  
-* Enable repeatability  
-* Codify operations knowledge  
-* Simplify day two 
-* Maintain portability
+Juju increases your productivity and decreases your costs.
+
+- **Increase confidence**  
+ If you have ever put off upgrading something in production because something might break, then consider Juju.
+ Juju allows applications to automatically negotiate their configuration, creating optimal settings dynamically.
+
+
+- **Reduce complexity**  
+ Microservices have made applications simpler, but operations more complex.
+ Regain your understanding of the whole stack.
+
 
-If your infrastructure can’t be understood by everyone in your organisation, there’s an issue.
-Juju focuses on the applications that your deployment defines and how they are related.
+- **Strengthen operations knowledge**  
+ Everyone has their in-house expert.
+ Encapsulating their know-how in charms distributes that knowledge throughout the business.
 
-Requiring everyone to know every hostname, every machine, every subnet and every storage volume is brittle.
-This means change is complicated, on-boarding is difficult and tends to create knowledge silos.
-Juju makes those details available, but places the deployment model at the front.
 
-With Juju, your team maintains a practical high-level view that makes your backend more adaptable to changes over time. 
-Extending your product should be as simple as deploying its first prototype.
+- **Simplify day two and beyond**  
+ Upgrades, provisioning new capacity, applying configuration changes can be subtle and difficult.
+ Juju takes responsibility for them, as well as deployment.
 
 
-## What is Juju?
+ - **Maintain portability and repeatability**  
+ Retain control over your deployment and eliminate the need for vendor-specific offerings.
+ Your devops tooling should be cloud-agnostic and Kubernetes-aware.
 
-Juju is a devops tool that reduces operational complexity through application modelling.
-Once a model is described, Juju identifies the necessary steps to make that model a reality.
 
-Juju has three core concepts: models, applications and relations.
-Consider a whiteboard drawing of your service.
-The whiteboard's border is the model, its circles are applications and the lines between the circles are relations.
+## Get started
 
-Juju uses an active agent deployed alongside your applications.
-That agent orchestrates infrastructure, and manages applications through the product life cycle.
+[Install Juju][] and [get started][] with your first project.
 
+Read the [project’s documentation](https://jaas.ai/docs).
 
-## Next steps
+Explore questions and conversations on our [Discourse forum](https://jaas.ai/docs).
 
-Read the documentation https://jaas.ai/docs
+Developers are welcome to read through our [contributing guidelines](CONTRIBUTING.md) to learn how to make code changes.
 
-Ask a question https://discourse.jujucharms.com/
+Find out more, get help or ask questions on our [Freenode IRC channel](https://discourse.jujucharms.com/).
 
-Install Juju https://jaas.ai/docs/installing
+  [Install Juju]: https://jaas.ai/docs/install
+  [get started]: https://jaas.ai/docs/getting-started