Sync changes from upstream repository

Hubot · Hubot · commit a620e0e7b9e2 · 2016-04-06T10:37:00.000-07:00
diff --git a/content/changes/2016-04-06-deployment-and-deployment-status-enhancements.md b/content/changes/2016-04-06-deployment-and-deployment-status-enhancements.md
@@ -0,0 +1,49 @@
+---
+title: Deployment and DeploymentStatus API enhancements preview period
+author_name: tarebyte
+---
+
+We've expanded our Deployments APIs to accommodate more powerful deployment practices and to lay the foundation for a more seamless integration of deployments within GitHub.
+
+## Link to a live deployment
+
+To enable easy access to a live version of a deployment, we've added an `environment_url` field to the Deployments API. This environment will be exposed as a link in the Pull Request timeline to enable users to directly access a running version of their code without leaving the context of their work.
+
+*Note: To add some clarity, we've renamed the `target_url` field to `log_url`. We will continue accept `target_url` to support legacy uses, but we recommend modifying this to the new name to avoid confusion. Future API versions might not support `target_url`*.
+
+## Inactive deployment status
+
+We recognize that deployments in many common practices don't last forever. So, we've added a new `inactive` state to Deployment Statuses. You can use this state to communicate that a deployment is no longer active (e.g. something different has been deployed to the environment or the environment has been destroyed).
+
+## More information about environments
+
+We've expanded our Deployments API to provide additional information about the environments associated with deployments.
+
+We've added a new `transient_environment` field to allow you to communicate that an environment is specific to a deployment and will no longer exist at some point in the future (e.g. a temporary testing environment like a [Heroku Review App][heroku-review-app]). By pairing this with other additions, we can determine that an `inactive` deployment associated with a `transient_environment` has an `environment_url` that is no longer accessible.
+
+Similarly, we've added a new `production_environment` field to allow you to communicate that an environment is one with which end users directly interact. We automatically set `production_environment` to `true` if the value for `environment` is ``"production"``.
+
+## Automatic creation of inactive statuses
+
+Each time we receive a new successful deployment status, we automatically add a new `inactive` status to all previous deployments made within the relevant repository to the same environment (based on the value of `environment`) given the environment is both non-transient and non-production. You can opt out of this behavior by passing `false` with the new `auto_inactive` parameter.
+
+For example, if `feature-branch` within `https://github.com/user/repository` is deployed to an environment named `staging` (which is a non-transient, non-production environment) and `bugfix-branch` within `https://github.com/user/repository` is later deployed to an environment named `staging`, we would automatically create a new `inactive` status for the deployment associated with `feature-branch`.
+
+#### How can I try it?
+
+Starting today, these API enhancements are available for developers to preview. At the end of the preview period, these enhancements will become official components of the GitHub API.
+
+To access the API during the preview period, you must provide a custom [media type][media-types] in the Accept header:
+
+```
+application/vnd.github.ant-man-preview+json
+```
+
+During the preview period, we may change aspects of these enhancements. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.
+
+Take a look at [the documentation][docs] for full details. We would love to hear your thoughts on these enhancements. If you have any questions or feedback, please [get in touch with us][contact]!
+
+[contact]: https://github.com/contact?form%5Bsubject%5D=Deployment+and+DeploymentStatus+API+enhancements+preview+period
+[media-types]: /v3/media/
+[heroku-review-app]: https://devcenter.heroku.com/articles/github-integration-review-apps
+[docs]:https://developer.github.com/v3/repos/deployments/
diff --git a/content/v3/repos/deployments.md b/content/v3/repos/deployments.md
@@ -138,6 +138,23 @@ Name | Type | Description
 `payload`|`string` | Optional JSON payload with extra information about the deployment. Default: `""`
 `environment`|`string` | Optional name for the target deployment environment (e.g., production, staging, qa). Default: `"production"`
 `description`|`string` | Optional short description. Default: `""`
+{% if page.version == 'dotcom' || page.version >= 2.6 %} `transient_environment` | `boolean` | Optionally specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: `false` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+{% if page.version == 'dotcom' || page.version >= 2.6 %} `production_environment` | `boolean` | Optionally specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `"production"` and `false` otherwise. **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+
+{% if page.version == 'dotcom' || page.version >= 2.6 %}
+{{#tip}}
+
+The new `transient_environment` and `production_environment` parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the [blog post][blog-post] for full details.
+
+To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header:
+
+```
+application/vnd.github.ant-man-preview+json
+```
+
+{{/tip}}
+
+{% endif %}
 
 #### Simple Example
 
@@ -221,9 +238,28 @@ Users with push access can create deployment statuses for a given deployment:
 
 Name | Type | Description
 -----|------|--------------
-`state`|`string` | **Required**. The state of the status. Can be one of `pending`, `success`, `error`, or `failure`.
+`state`|`string` | **Required**. The state of the status. Can be one of `pending`, `success`, `error`, {% if page.version == 'dotcom' || page.version >= 2.6 %} `inactive`, {% endif %}or `failure` **The `inactive` state requires a custom media type to be specified. Please see more in the alert below.**.
 `target_url`|`string` | The target URL to associate with this status.  This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Default: `""`
+{% if page.version == 'dotcom' || page.version >= 2.6 %}`log_url`|`string` | This is functionally equivalent to `target_url`. We will continue accept `target_url` to support legacy uses, but we recommend modifying this to the new name to avoid confusion. Default: `""` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
 `description`|`string` | A short description of the status. Maximum length of 140 characters. Default: `""`
+{% if page.version == 'dotcom' || page.version >= 2.6 %}`environment_url`|`string`| Optionally set the URL for accessing your environment. Default: `""` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+{% if page.version == 'dotcom' || page.version >= 2.6 %}`auto_inactive`|`boolean`| Optional parameter to add a new `inactive` status to all non-transient, non-production environment deployments with the same repository and environment name as the created status's deployment. Default: `true` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+
+{% if page.version == 'dotcom' || page.version >= 2.6 %}
+
+{{#tip}}
+
+The new `inactive` state,  rename of the `target_url` parameter to `log_url` and new `environment_url` and `auto_inactive` parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the [blog post][blog-post] for full details.
+
+To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header:
+
+```
+application/vnd.github.ant-man-preview+json
+```
+
+{{/tip}}
+
+{% endif %}
 
 #### Example
 
@@ -237,3 +273,5 @@ Name | Type | Description
 
 <%= headers 201, :Location => get_resource(:deployment_status)['url'] %>
 <%= json :deployment_status %>
+
+[blog-post]: /changes/2016-04-06-deployment-and-deployment-status-enhancements
