diff --git a/docs/README.md b/docs/README.md
index 3beb48528..65d8c17d3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,7 +23,9 @@ English | [简体中文](zh/README.md)
 
 ## Release notes
 
- * [3.0](v3.0.0.md) - Late June 2019.  Plugin developer release.
+ * [3.1](v3.1.0.md) - Late July 2019. Extended patches and improved resource matching.
+
+ * [3.0](v3.0.0.md) - Late June 2019. Plugin developer release.
 
  * [2.1](v2.1.0.md) - 18 June 2019.  Plugins, ordered resources, etc.
 
diff --git a/docs/v3.1.0.md b/docs/v3.1.0.md
new file mode 100644
index 000000000..f847ad1d9
--- /dev/null
+++ b/docs/v3.1.0.md
@@ -0,0 +1,127 @@
+# kustomize 3.1.0
+
+
+## Extended patches
+Since this version, Kustomize allows applying one patch to multiple resources. This works for both Strategic Merge Patch and JSON Patch. Take a look at [patch multiple objects](../examples/patchMultipleObjects.md).
+
+## Improved Resource Matching
+
+Multiple improvements have been made to allow the user to leverage "namespace"
+instead/or with "name suffix/prefix" to segregate resources.
+
+### Patch resolution improvement
+
+The following example demonstrates how using the namespace field in the patch definition,
+will let the user define two different patches against two different Deployment having the
+same "deploy1" name but in different namespaces in the same Kustomize context/folder.
+Unless the `namespace:` field has been specified in the kustomization.yaml, no namespace
+value will be handled as Kubernetes `default` namespace.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy1
+  namespace: main
+spec:
+  template:
+    spec:
+      containers:
+      - name: nginx
+        env:
+        - name: ANOTHERENV
+          value: TESTVALUE
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy1
+  namespace: production
+spec:
+  template:
+    spec:
+      containers:
+      - name: main
+        env:
+        - name: ANOTHERENV
+          value: PRODVALUE
+```
+
+
+### Variable resolution improvement
+
+It is possible to add namespace field to the variable declaration. In the following example,
+two `Service` objects with the same `elasticsearch` name have been declared.
+Specifying the namespace in the objRef of the corresponding varriables, allows Kustomize to
+resovlve thoses variables.
+If the namespace is not specified, Kustomize will handle it has a "wildcard" value.
+
+Extract of kustomization.yaml:
+
+```yaml
+vars:
+- name: elasticsearch-test-protocol
+  objref:
+    kind: Service
+    name: elasticsearch
+    namespace: test
+    apiVersion: v1
+  fieldref:
+    fieldpath: spec.ports[0].protocol
+- name: elasticsearch-dev-protocol
+  objref:
+    kind: Service
+    name: elasticsearch
+    namespace: dev
+    apiVersion: v1
+  fieldref:
+    fieldpath: spec.ports[0].protocol
+
+```
+
+### Simultaneous change of names and namespaces
+
+Kustomize is now able to deal with simultaneous changes of name and namespace.
+Special attention has been paid the handling of: 
+- ClusterRoleBinding/RoleBinding "subjects" field,
+- ValidatingWebhookConfiguration "webhooks" field.
+
+The user should be able to use a kustomization.yaml as shown in the example bellow
+even if ClusterRoleBind,RoleBinding and ValidatingWebookConfiguration are part of the
+resources he needs to declare.
+
+Extract of kustomization.yaml:
+
+```yaml
+namePrefix: pfx-
+nameSuffix: -sfx
+namespace: testnamespace
+
+resources:
+...
+```
+
+### Resource and Kustomize Context matching.
+
+Kustomize is now able to support more aggregation patterns.
+
+If for instance, the top level of kustomization.yaml, is simply
+combining sub-components, (as in the following example), Kustomize has improved
+resource matching capabilities. This removes some of the constraints which were
+present on the utilization of prefix/suffix and namespace transformers in the
+individual components.
+
+```yaml
+resources:
+- ../component1
+- ../component2
+- ../component3
+```
+
+## Other improvements
+
+- Image transformation has been improved. This allows the user to update the sha256 of
+  an image with another sha256.
+- Multiple default transformer configuration entries have been added, removing the need for the
+  user to add them as part of the `configurations:` section of the kustomization.yaml.
+- `kustomize` help command has been tidied up.