8000 Sync changes from upstream repository · maiamatheus/developer.github.com@62ea15b · GitHub
[go: up one dir, main page]
Skip to content

Commit 62ea15b

Browse files
author
Hubot
committed
Sync changes from upstream repository
1 parent b6e23bb commit 62ea15b

File tree

3 files changed

+54
-19
lines changed

3 files changed

+54
-19
lines changed

‎content/changes/2016-02-19-source-import-preview-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Preview the Source Import API
33
author_name: spraints
44
---
55

6-
We've added an API for source imports, which will let you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://import.github.com/).
6+
We've added an API for source imports, which will let you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://help.github.com/articles/importing-from-other-version-control-systems-to-github/).
77

88
To access [the Source Import API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header:
99

‎content/v3/migration/source_imports.md‎

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ This API is not currently available on GitHub Enterprise.
2424

2525
{{/tip}}
2626

27-
The Source Import API lets you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://import.github.com/).
27+
The Source Import API lets you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://help.github.com/articles/importing-from-other-version-control-systems-to-github/).
2828

2929
A typical source import would [start the import](#start-an-import) and then (optionally) [update the authors](#map-a-commit-author) and/or [set the preference](#set-git-lfs-preference) for using Git LFS if large files exist in the import. A more detailed example can be seen in this diagram:
3030

@@ -156,11 +156,17 @@ An import that does not have errors will progress through these steps:
156156

157157
If there are problems, you will see one of these in the `status` field:
158158

159-
* `auth_failed` - the import requires authentication in order to connect to the original repository. Make an "Update Existing Import" request, and include `vcs_username` and `vcs_password`.
159+
* `auth_failed` - the import requires authentication in order to connect to the original repository. To update authentication for the import, please see the [Update Existing Import](#update-existing-import) section.
160160
* `error` - the import encountered an error. The import progress response will include the `failed_step` and an error message. [Contact support](https://github.com/contact?form%5Bsubject%5D=Source+Import+API+error) for more information.
161-
* `detection_needs_auth` - the importer requires authentication for the originating repository to continue detection. Make an "Update Existing Import" request, and include `vcs_username` and `vcs_password`.
162-
* `detection_found_nothing` - the importer didn't recognize any source control at the URL.
163-
* `detection_found_multiple` - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a `project_choices` field with the possible project choices as values. Make an "Update Existing Import" request, and include `vcs` and (if applicable) `tfvc_project`.
161+
* `detection_needs_auth` - the importer requires authentication for the originating repository to continue detection. To update authentication for the import, please see the [Update Existing Import](#update-existing-import) section.
162+
* `detection_found_nothing` - the importer didn't recognize any source control at the URL. To resolve, [Cancel the import](#cancel-an-import) and [retry](#start-an-import) with the correct URL.
163+
* `detection_found_multiple` - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a `project_choices` field with the possible project choices as values. To update project choice, please see the [Update Existing Import](#update-existing-import) section.
164+
165+
### The `project_choices` field
166+
167+
When multiple projects are found at the provided URL, the response hash will include a `project_choices` field, the value of which is an array of hashes each representing a project choice. The exact key/value pairs of the project hashes will differ depending on the version control type.
168+
169+
<%= json :source_import_project_choices %>
164170

165171
### Git LFS related fields
166172

@@ -173,15 +179,10 @@ This section includes details about Git LFS related fields that may be present i
173179

174180
## Update existing import
175181

176-
An import can be updated with credentials or a `project_choice` by passing in the appropriate parameters in this API request. If no parameters are provided, the import will be restarted.
182+
An import can be updated with credentials or a project choice by passing in the appropriate parameters in this API request. If no parameters are provided, the import will be restarted.
177183

178184
PATCH /repos/:owner/:repo/import
179185

180-
### Response
181-
182-
<%= headers 200, :Location => "https://api.github.com/repos/spraints/socm/import" %>
183-
<%= json :source_import %>
184-
185186
### Parameters for updating authentication
186187

187188
Name | Type | Description
@@ -203,23 +204,34 @@ Name | Type | Description
203204

204205
### Parameters for updating project choice
205206

206-
Name | Type | Description
207-
-----|------|--------------
208-
`vcs`|`string`|The chosen project's VCS type.
209-
`tfvc_project`|`string`|For a tfvc import, the name of the project that is being imported.
207+
Some servers (e.g. TFS servers) can have several projects at a single URL. In those cases the import progress will have the status `detection_found_multiple` and the Import Progress response will include a `project_choices` array. You can select the project to import by providing one of the objects in the `project_choices` array in the update request.
208+
209+
The following example demonstrates the workflow for updating an import with "project1" as the project choice. Given a `project_choices` array like such:
210+
211+
<%= json :source_import_project_choices %>
210212

211213
### Example
212214

213215
<%= json\
214-
:vcs => "tfvc",
215-
:tfvc_project => "project"
216+
"vcs": "tfvc",
217+
"tfvc_project": "project1",
218+
"human_name": "project1 (tfs)"
216219
%>
217220

218221
### Response
219222

220223
<%= headers 200 %>
221224
<%= json :source_import_update_project_choice %>
222225

226+
### Parameters for restarting import
227+
228+
To restart an import, no parameters are provided in the update request.
229+
230+
### Response
231+
232+
<%= headers 200, :Location => "https://api.github.com/repos/spraints/socm/import" %>
233+
<%= json :source_import %>
234+
223235
## Get commit authors
224236

225237
Each type of source control system represents authors in a different way. For example, a Git commit author has a display name and an email address, but a Subversion commit author just has a username. The GitHub Importer will make the author information valid, but the author might not be correct. For example, it will change the bare Subversion username `hubot` into something like `hubot <hubot@12341234-abab-fefe-8787-fedcba987654>`.

‎lib/responses/source_imports.rb‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ module Responses
5151
"vcs" => "tfvc",
5252
"use_lfs": "undecided",
5353
"vcs_url" => "http://tfs.mycompany.com/tfs/myproject",
54-
"tfvc_project": "project",
54+
"tfvc_project": "project1",
5555
"status" => "importing",
5656
"status_text" => "Importing...",
5757
"has_large_files" => false,
@@ -66,6 +66,29 @@ module Responses
6666
"repository_url" => "https://api.github.com/repos/octocat/socm"
6767
}
6868

69+
SOURCE_IMPORT_PROJECT_CHOICES ||= [
70+
{
71+
"vcs": "tfvc",
72+
"tfvc_project": "project0",
73+
"human_name": "project0 (tfs)"
74+
},
75+
{
76+
"vcs": "tfvc",
77+
"tfvc_project": "project1",
78+
"human_name": "project1 (tfs)"
79+
},
80+
{
81+
"vcs": "tfvc",
82+
"tfvc_project": "project2",
83+
"human_name": "project2 (tfs)"
84+
},
85+
{
86+
"vcs": "tfvc",
87+
"tfvc_project": "project3",
88+
"human_name": "project3 (tfs)"
89+
}
90+
]
91+
6992
SOURCE_IMPORT_AUTHOR ||= {
7093
"id" => 2268557,
7194
"remote_id" => "nobody@fc7da526-431c-80fe-3c8c-c148ff18d7ef",

0 commit comments

Comments
 (0)
0