Tciasm handshake documentation update (#3338)

* Add P4 and SVN .travis.yml instructions to Assembla section

Paths to put .travis.yml in P4 and SVN repositories at Assembla

* Fix direct Travis CI app links

Updated multiple links to be directly referring to the Travis CI web app when instructions tell user to 'go to Travis and...'

* Added references to pages clarifying access rights exercised  by Travis CI with VCSes

* removed travis-ci.org section as all is now under travis-ci.com

* Added extended information on Assembla SVN and P4 access exercised by Travis CI

* updated layout and links

* moved Assembla behind GitHub
* added shared build config imports link to 'further reading' section

* Added 'important' to Assembla section

* commas to colons

* Assembla after GitHub - fix

* Update assembla-oauth-scopes.md

reviewed

* Update tutorial.md

reviewed

---------

Co-authored-by: nrios14 <[email protected]>

Author: michal-at-travisci

user/assembla-oauth-scopes.md

@@ -5,7 +5,7 @@ permalink: /user/assembla-oauth-scopes/
 
 ---
 
-When you sign in to Travis CI for the first time, we ask for permissions to access
+When you sign in to Travis CI for the first time, we ask permission to access
 some of your data on Assembla. Read the
 [Scopes for the Assembla REST API](https://api-docs.assembla.cc/)
 for general information about this, or pick an explanation of what data we need and why we need it.
@@ -25,33 +25,60 @@ We use scoped OAuth tokens to integrate with Assembla.
 ## Used Scopes
 
 ### repository
-Gives the app read access to all the repositories the authorizing user has access to.
+It gives the app read access to all the repositories the authorizing user has access to.
 > This scope does not give access to a repository's pull requests.
 
 ### repository:admin
-Gives the app admin access to all the repositories the authorizing user has access to. This permission is needed to add the access key. Travis CI uses the key to read the travis.yml file content.
+It gives the app admin access to all the repositories the authorizing user has access to. This permission is needed to add the access key. Travis CI uses the key to read the travis.yml file content.
 
 
 ### pullrequest
-Gives the app read access to pull requests and collaborate on them. This scope implies repository, giving read access to the pull request's destination repository.
+It gives the app read access to pull requests and collaborate on them. This scope implies a repository giving read access to the pull request's destination repository.
 
 ### email
-Ability to see the user's primary email address. This should make it easier to use Assembla as a login provider to apps or external applications.
+The ability to see the user's primary email address. This should make using Assembla as a login provider to apps or external applications easier.
 
 ### account
-Ability to see all the user's account information. Note that this does not include any ability to mutate any of the data.
+The ability to see all the user's account information. Note that this does not include any ability to mutate the data.
 
 ### team
-The ability to find out what teams the current user is part of. This is covered by the teams endpoint.
+The ability to find out what teams the current user is part of. The teams' endpoint covers this.
 
 ### webhook
-Gives access to webhooks. This scope is required for any webhook related operation.
+Gives access to webhooks. This scope is required for any webhook-related operation.
 
-This scope gives read access to existing webhook subscriptions on all resources you can access, without needing further scopes.
-This means that a client can list all existing webhook subscriptions on repository foo/bar (assuming the principal user has access
-to this repo). The additional repository scope is not required for this.
+This scope gives read access to existing webhook subscriptions on all resources you can access without needing further scopes.
+This means a client can list all existing webhook subscriptions on repository foo/bar (assuming the principal user can access
+this repo). The additional repository scope is not required for this.
 
 Likewise, existing webhook subscriptions for a repo's issue tracker can be retrieved without holding the issue scope.
 All that is required is the webhook scope.
 
 However, to create a webhook for issue:created, the client will need to have both the webhook as well as issue scope.
+
+## Version Control System Specific Information
+
+Aside from Git Repository integration, Travis CI supports the following VCS (Version Control System) integrations with Assembla:
+
+| Repository type     | Supported integration                | Authorization engine                                    |
+| ------------------- | ------------------------------------ | ------------------------------------------------------- |
+| Perforce Helix Core | Streams mainline and dev depots only | Ticket-based authorization only                         |
+| SVN                 | Apache SVN server only               | svn+ssh (implies SSH keys used) + optionally use realms |
+
+### SVN
+
+When enabling the Assembla SVN Repository in Travis CI, the 'write access' SSH deploy key with the title 'travis-ci.com' is 
+added to the Assembla SVN Repository Settings. This is the current Assembla requirement for authorizing the connection. 
+Travis CI does not require write access to your repositories. Only read access is needed to set up the connection and 
+trigger builds in Travis CI. 
+The svn+ssh protocol is used to obtain an SVN repository copy into the ephemerical build job environment for the time 
+needed to execute build instructions.
+
+### Perforce Helix Core (P4)
+
+When enabling the Assembla P4 Repository in Travis CI, a special access group is created for this P4 repository in Assembla. 
+You can see it in the respective 'P4 Admin' section for the enabled P4 repository. It will be named 'TravisCIAccessGroup-<guid>'
+and login timeout for the group will be set so the ticket-based authorization does not expire until the repository is disabled 
+in Travis CI. The group will contain the Assembla user-enabling repository in Travis CI.
+This is required for the Travis CI build job to communicate with Assembla P4 and obtain a copy of the source code to the ephemerical
+build job environment for the time needed to execute build instructions.

user/github-oauth-scopes.md

@@ -50,51 +50,3 @@ Before GitHub Apps, we used scoped OAuth tokens to integrate with GitHub. As of
     deployment statuses for public and private repositories and organizations.
 
     We need this level of access because GitHub does not provide the `read:org` (read-only) scope for private repositories.
-
-### Repositories on https://travis-ci.org
-
-On <https://travis-ci.org> we ask for the following permissions:
-
-  - `user:email` (read-only)
-
-      We synchronize your email addresses so we can email you build
-        notifications.
-
-      Your email address can be hidden from the GitHub profile, which also hides it from us.
-
-  - `read:org` (read-only)
-
-      When you're logged in on Travis CI, we show you all of your repositories,
-      including the ones from any organization you're part of.
-
-      The GitHub API hides any organizations you're a private member of without
-      this scope. So to make sure we show you all of your repositories, we require
-      this scope.
-
-      Note that this scope allows access to the basic information about both private
-      and public repositories, but not on any of the data or code stored in them.
-
-  - `repo_deployment`
-
-      Gives us access to the [upcoming deployments
-      API](http://developer.github.com/v3/repos/deployments/), currently in preview mode.
-
-      This scope currently isn't actively used, but will be in the future.
-
-  - `repo:status`
-
-      After every build, we update the status of its commit, which is most
-      relevant for testing pull request. This scope gives us the permission to
-      update the commit status as the build starts and finishes.
-
-  - `write:repo_hook`
-
-      Building a new repository on Travis CI is as easy as enabling it in your
-      profile and pushing a new commit.
-
-      Updating the webhook required for us to be notified from GitHub on new
-      commits or pull requests requires this API scope. Additionally, your user
-      needs to have admin access to the repository you want to enable.
-
-    Note that for open source projects, we don't have any write access to your source
-    code or your profile.