update docs

README.md

@@ -271,6 +271,7 @@ As seen above, we have two steps. One for a noop deploy, and one for a regular d
 | `production_environments` | `false` | `production` | A comma separated list of environments that should be treated as "production". GitHub defines "production" as an environment that end users or systems interact with. Example: "production,production-eu". By default, GitHub will set the "production_environment" to "true" if the environment name is "production". This option allows you to override that behavior so you can use "prod", "prd", "main", "production-eu", etc. as your production environment name. ref: [#208](https://github.com/github/branch-deploy/issues/208) |
 | `stable_branch` | `false` | `main` | The name of a stable branch to deploy to (rollbacks). Example: "main" |
 | `update_branch` | `false` | `warn` | Determine how you want this Action to handle "out-of-date" branches. Available options: "disabled", "warn", "force". "disabled" means that the Action will not care if a branch is out-of-date. "warn" means that the Action will warn the user that a branch is out-of-date and exit without deploying. "force" means that the Action will force update the branch. Note: The "force" option is not recommended due to Actions not being able to re-run CI on commits originating from Actions itself |
+| `outdated_mode` | `false` | `"strict"` | The mode to use for determining if a branch is up-to-date or not before allowing deployments. This option is closely related to the `update_branch` input option above. There are three available modes to choose from: `pr_base`, `default_branch`, or `strict`. The default is `strict` to help ensure that deployments are using the most up-to-date code. Please see the [documentation](docs/outdated_mode.md) for more details. |
 | `required_contexts` | `false` | `"false"` | Manually enforce commit status checks before a deployment can continue. Only use this option if you wish to manually override the settings you have configured for your branch protection settings for your GitHub repository. Default is "false" - Example value: "context1,context2,context3" - In most cases you will not need to touch this option |
 | `skip_ci` | `false` | `""` | A comma separated list of environments that will not use passing CI as a requirement for deployment. Use this option to explicitly bypass branch protection settings for a certain environment in your repository. Default is an empty string `""` - Example: `"development,staging"` |
 | `skip_reviews` | `false` | `""` | A comma separated list of environment that will not use reviews/approvals as a requirement for deployment. Use this options to explicitly bypass branch protection settings for a certain environment in your repository. Default is an empty string `""` - Example: `"development,staging"` |

docs/outdated_mode.md

@@ -0,0 +1,23 @@
+# Outdated Mode
+
+> Issue [#253](https://github.com/github/branch-deploy/issues/235) contains a great discussion about the outdated mode and why it was added as a feature to this project.
+
+The `outdated_mode` input option gives you the ability to determine how the branch-deploy Action should handle outdated branches. This input option is closely related to the `update_branch` input option as well.
+
+## Using the `outdated_mode` input option
+
+The `outdated_mode` input option has three possible values:
+
+- `strict` (default): The branch-deploy Action will consider your branch (that you are deploying) to be out-of-date if it is behind the default|stable branch (i.e `main`) or if it is behind the branch that your pull request is merging into.
+- `pr_base`: The branch-deploy Action will consider your branch (that you are deploying) to be out-of-date if it is behind the branch that your pull request is merging into.
+- `default_branch`: The branch-deploy Action will consider your branch (that you are deploying) to be out-of-date if it is behind the default|stable branch (i.e `main`). The `default_branch` is determined by the value you have set for the `stable_branch` input option. By default, the value of the `stable_branch` input option is `main`.
+
+If your branch is determined to be out-of-date, the branch-deploy Action will not deploy your branch. What happens next is determined by the value of the `update_branch` input option. Here are the three possible values for the `update_branch` input option and how they will operate:
+
+- `warn`: The branch-deploy Action will leave a comment on your pull request indicating that your branch is out-of-date and that you should update it before it can be deployed.
+- `force`: The branch-deploy Action will attempt to update your branch by merging the latest commits into your branch for you. You will need to re-run the deployment command after the branch-deploy Action has attempted to update your branch.
+- `disabled`: The branch-deploy Action will allow you to deploy your branch even if it is out-of-date. (dangerous)
+
+## About the `outdated_mode` input option
+
+The `outdated_mode` input option is useful when you want to ensure that the branch-deploy Action only deploys branches that are up-to-date. This is especially useful when you have a large team of developers working on a project and you want to ensure that commits are not rolled back accidentally when you are deploying a branch. For the sake of availability and deployment confidence, this input option is set to `strict` by default. This will ensure that your branch is up-to-date with the latest commits from both the default|stable branch and the branch that your pull request is merging into.