docs: improve promote documentation

Signed-off-by: Mårten Svantesson <Marten.Svantesson@ticket.se>

content/en/v3/develop/environments/config.md

@@ -31,7 +31,7 @@ When you setup a [Remote Cluster](/v3/admin/guides/multi-cluster/) for `Staging`
 
 Then when you import the remote cluster repository into the development environment (to setup the CI/CD on pull requests and enable promotion) the generated Pull Request will modify your `jx-requirements.yml` to add remote entries for the remote cluster.
 
-e.g. after importing the remote `production` environment via [jx project import](/v3/develop/reference/jx/project/import) and the pull request merging it should look like: 
+E.g. after importing the remote `production` environment via [jx project import](/v3/develop/reference/jx/project/import) and the pull request merging it should look like: 
 
 ```yaml 
 apiVersion: core.jenkins-x.io/v4beta1
@@ -50,9 +50,15 @@ spec:
 
 ## Custom environments per repository
 
-If you wish to use different sets of environments for different microservices you can override the environments that are used for promotion by adding a `.jx/settings.yaml` with [this format](https://github.com/jenkins-x/jx-api/blob/master/docs/config.md#settings) which overrides settings found the development environments [jx-requirements.yml](https://github.com/jenkins-x/jx-api/blob/master/docs/config.md#requirements) file.
+If you wish to use different sets of environments for different microservices you can augment the environments that are 
+used for promotion by adding a `.jx/settings.yaml` with [this format](https://github.
+com/jenkins-x/jx-api/blob/master/docs/config.md#settings) which is merged with settings for the development 
+cluster repository's [jx-requirements.yml](https://github.com/jenkins-x/jx-api/blob/master/docs/config.
+md#requirements) file. If you want to override the environments instead of augment you can set 
+`ignoreDevEnvironments: true`. By default the namespace name is the environment name prefixed with `jx-`.
 
-e.g. add something like this to your `.jx/settings.yaml` in a repository to override which environment repositories are promoted to:
+E.g. add something like this to your `.jx/settings.yaml` in a repository to override which environment repositories 
+are promoted to:
 
 ```yaml 
 apiVersion: core.jenkins-x.io/v4beta1
@@ -64,9 +70,23 @@ spec:
   - key: my-staging
     owner: myowner
     repository: some-repo-name
+    promotionStrategy: Auto
   - key: my-prod
     owner: myowner
-    repository: some-other-repo-name    
+    repository: some-other-repo-name
+    promotionStrategy: Manual
+```
+
+If you instead want to disable promotion to an environment, say staging, you can do it with a `.jx/settings.yaml` 
+looking like this:
+
+```yaml 
+apiVersion: core.jenkins-x.io/v4beta1
+kind: Settings
+spec:
+  promoteEnvironments:
+  - key: staging
+    promotionStrategy: Never
 ```
 
 ## Custom environments per group of repositories
@@ -77,7 +97,7 @@ The simplest way to do this is to use a separate git organisation (owner) per te
 
 The added benefit of using separate git organisations is that already the [dashboard](/v3/develop/ui/dashboard/) supports filtering all pipelines by owner; so each team will get effectively their own separate UI for viewing pipelines. You can easily bookmark the dashboards view for a single owner / repository.
 
-e.g. here's an example `.jx/gitops/source-config.yaml in the development cluster git repository:
+E.g. here's `.jx/gitops/source-config.yaml in the development cluster git repository:
 
 ```yaml 
 apiVersion: gitops.jenkins-x.io/v1alpha1

content/en/v3/develop/environments/promotion/_index.md

@@ -10,25 +10,45 @@ When changes are merged to the main branch in the Jenkins X pipeline catalog a n
 
 ## How it works
 
-The release pipelines use the [jx promote --all](https://github.com/jenkins-x/jx-promote/blob/master/docs/cmd/jx-promote.md#jx-promote) command which creates Pull Requests on all Environments configured in your `jx-requirements.yml` file (see the [Configuration](/v3/develop/environments/config/)) 
+The release pipelines use the [jx promote --all](https://github.
+com/jenkins-x/jx-promote/blob/master/docs/cmd/jx-promote.md#jx-promote) command which creates Pull Requests on all 
+Environments configured in your `jx-requirements.yml` file and possibly `.jx/gitops/source-config.yaml` or 
+`.jx/settings.yaml` (see the [Configuration](/v3/develop/environments/config/)).
 
-* every environment which is defined in `jx-requirements.yml` as `promotionStrategy` **Auto** or **Manual** is included in a Pull Request to promote the new version to that environment
+* every environment which is defined as `promotionStrategy` **Auto** or **Manual** is included in a Pull Request to promote the new version to that environment
 
   * **Auto** means the Pull Request will automatically merge if its successful (the Pull Request pipeline succeeds)
 
   * **Manual** means the Pull Request is a draft and won't automatically merge. i.e. the Pull Request needs to be manually approved (comment `/approve`) and taken off hold (comment `/hold cancel`). 
 
-* all local Environments in your `jx-requirements.yml` of the promotion kind **Auto** are promoted using a single Pull Request so that all the promotions automatically merge if the pull request pipeline validates successfully.
+* all local Environments of the promotion kind **Auto** are promoted using a single Pull Request so that all the promotions automatically merge if the pull request pipeline validates successfully.
 
 * you can define multiple local or remote Environments for different system / integration testing environments.
 
 
-## Changing Promotion
+## Disable Promotion
 
-If you want to disable promotion Pull Requests on an environment just remove the entry in `jx-requirements.yml` or configure the `promotionStrategy` to be **Never**
+If you want to disable promotion Pull Requests on an environment just remove the entry or configure the 
+`promotionStrategy` to be **Never**.
 
-If you want your application to promote to different environments to the defaults for your cluster you can always [modify your pipeline](/v3/develop/pipelines/#editing-pipelines) and change the promote step to use different [jx promote](https://github.com/jenkins-x/jx-promote/blob/master/docs/cmd/jx-promote.md#jx-promote) arguments; e.g. pass in the explicit environments or repositories you want to promote to in the pipeline step.
+## Reuse pull requests
 
+By default a new pull request is created for each promotion. You can instead make existing open pull requests for 
+promoting an application be reused. 
+
+Enabling reuse of pull requests for `jx promote` is done in `jx-requirements.yaml` by setting `reusePullRequest` to 
+`true` for an environment. It can also be done in the same way when configuring environments others ways. See 
+https://jenkins-x.io/v3/develop/environments/config/ for more details about configuring environments.
+
+There are two main reasons why you would want to enable this:
+
+To reduce conflicts: if a pull request is created before a previous pull request for upgrading the same application is 
+merged there will be a conflict when the earlier pull request is merged. Since enabling reuse means that `jx 
+promote` won't open more pull requests for an application this can't happen. 
+
+The other reason is if you make use of the functionality to propagate application changelogs to cluster 
+repositories. This is described in the blog post
+[Improve your changelogs](/blog/2023/05/24/propagate-changelogs/#reuse-pull-requests).
 
 ## Synchronizing environments or namespaces