diff --git a/docs/builds.md b/docs/builds.md index edd8c128..3f802661 100644 --- a/docs/builds.md +++ b/docs/builds.md @@ -2,20 +2,22 @@ You can queue, show, and list builds using tfx. -## Queue +## Build Queue Queues a build for a given project with a given definition. -### Options +### Build Queue Options + ```txt ---project - Required. The name of the project to queue a build for. +--project - Required. The name of the project to queue a build for. AND --definition-id - The id of the build definition to build against. OR --definition-name - The name of the build definition to build against. ``` -### Example +### Build Queue Example + ```bash ~$ tfx build queue --project MyProject --definition-name TestDefinition Copyright Microsoft Corporation @@ -28,17 +30,19 @@ status : NotStarted queue time : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time) ``` -## Show +## Build Show Shows information for a given build. -### Options +### Build Show Options + ```txt --project - Required. The name of the project to queue a build for. --id - Required. The id of the build to show. ``` -### Example +### Build Show Example + ```bash $ tfx build show --project MyProject --id 1 Copyright Microsoft Corporation @@ -51,11 +55,12 @@ status : NotStarted queue time : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time) ``` -## List +## Build List Queries for a list of builds. -### Options +### Build List Options + ```txt --project - Required. The name of the project to queue a build for. --defintion-id - The id of a build definition. @@ -64,7 +69,8 @@ Queries for a list of builds. --top - Show the first X builds that satisfy the other query criteria. ``` -### Example +### Build List Example + ```bash ~$ tfx build list @@ -79,4 +85,3 @@ status : NotStarted queue time : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time) ``` - diff --git a/docs/buildtasks.md b/docs/buildtasks.md index fb58d5c6..4475b1f1 100644 --- a/docs/buildtasks.md +++ b/docs/buildtasks.md @@ -3,16 +3,17 @@ You can create, list, upload and delete build tasks with tfx. ## Permissions -You need to be in the top level Agent Pool Administrators group to manipulate tasks -[See here](https://msdn.microsoft.com/Library/vs/alm/Build/agents/admin) + +You need to be in the top level Agent Pool Administrators group to manipulate tasks. [See here](https://msdn.microsoft.com/Library/vs/alm/Build/agents/admin) Account admins can add users to that group -## Create +## Build Tasks Create Creates a templated task ready for you to start editing -### Example +### Build Tasks Create Example + ```bash ~$ tfx build tasks create Copyright Microsoft Corporation @@ -26,19 +27,20 @@ created task @ /Users/bryanmac/sample id : 305898e0-3eba-11e5-af7a-1181c3c6c966 name: sample -A temporary task icon was created. Replace with a 32x32 png with transparencies +A temporary task icon was created. Replace with a 32x32 png with transparencies ~$ ls ./sample icon.png sample.js sample.ps1 task.json ``` -## Upload +## Build Tasks Upload You can upload a task by specifying the directory (fully qualified or relative) which has the files. -As an example we can upload the Octopus Deploy custom task. +As an example we can upload the Octopus Deploy custom task. + +### Build Tasks Upload Example -### Example ```bash ~$ git clone https://github.com/OctopusDeploy/OctoTFS Cloning into 'OctoTFS'... @@ -47,7 +49,7 @@ Checking connectivity... done. ~$ cd OctoTFS/source/CustomBuildSteps ``` -It's task is in the +It's task is in the ```bash ~$ tfx build tasks upload --task-path ./CreateOctopusRelease @@ -55,11 +57,12 @@ It's task is in the Build tasks are cached by version on the agent. The implementation by that version is considered to be immutable. If you are changing the implementation and uploading, bump at least the patch version. -## List +## Build Tasks List To list the tasks that are on the server ... -### Example +### Build Tasks List Example + ```bash ~$ tfx build tasks list @@ -74,18 +77,18 @@ version: 0.1.2 ``` -## Delete +## Build Tasks Delete -You can delete a task by supplying the id. Use list above to get the id +You can delete a task by supplying the id. Use list above to get the id As an example, this would delete the Octopus task we uploaded above Of course, be cautious deleting tasks. -### Example +### Build Tasks Delete Example + ```bash ~/$ tfx build tasks delete --task-id 4e131b60-5532-4362-95b6-7c67d9841b4f Copyright Microsoft Corporation task: 4e131b60-5532-4362-95b6-7c67d9841b4f deleted successfully! ``` - diff --git a/docs/configureBasicAuth.md b/docs/configureBasicAuth.md index a2ddf659..2c37268b 100644 --- a/docs/configureBasicAuth.md +++ b/docs/configureBasicAuth.md @@ -1,9 +1,11 @@ # Using `tfx` against Team Foundation Server (TFS) 2015 using Basic Authentication + In order to use `tfx` against TFS on-premises, you will need to enable basic authentication in the tfs virtual application in IIS. _This is a temporary solution until NTLM authentication is supported._ > **WARNING!!** Basic authentication sends usernames and passwords in plaintext. You should consider [configuring TFS to use SSL](https://msdn.microsoft.com/en-us/library/aa833872.aspx) in order to enable secure communication when using basic auth. ## Configuring TFS to use Basic Authentication + Follow these steps to enable basic auth for your TFS: 1. Install the `Basic Authentication` feature for IIS in Server Manager. ![Basic Auth feature in Server Manager](configureBasicAuthFeature.png) @@ -12,16 +14,18 @@ Follow these steps to enable basic auth for your TFS: 4. **Note**: leave the `domain` and `realm` settings for `Basic Authentication` empty. ## `tfx login` with Basic Authentication + Now you can start to use `tfx` against your TFS server. You'll want to `login` before issuing commands. -1. Type `tfx login --auth-type basic` -2. You will be prompted to add your service Url. +* Type `tfx login --auth-type basic` +* You will be prompted to add your service Url. * **Note for TFS on-prem**: If the server name is part of the service URL, be sure to specify the fully-qualitifed domain name (FQDN) of that server (i.e. in the form _servername.domain.local_). Otherwise, TFX will fail to connect. -3. You will be prompted for your username. Use `domain\user` (e.g. fabrikam\peter). If you are on a workgroup machine, use `machinename\username`. -4. You will be prompted for your password. Enter the password for the username you entered. +* You will be prompted for your username. Use `domain\user` (e.g. fabrikam\peter). If you are on a workgroup machine, use `machinename\username`. +* You will be prompted for your password. Enter the password for the username you entered. You can now use any other `tfx` commands. -``` + +```bash > tfx login --auth-type basic Copyright Microsoft Corporation diff --git a/docs/contributions.md b/docs/contributions.md index 65a59ef5..987ffbd4 100644 --- a/docs/contributions.md +++ b/docs/contributions.md @@ -1,6 +1,6 @@ # Contributions -We accept contributions. Supply a pull request. +We accept contributions. Supply a pull request. ## Pre-reqs @@ -12,7 +12,7 @@ Install Dev Dependencies from root of repo: ## Build -We build the product using npm. Just type `npm run build` in the root of the repo. +We build the product using npm. Just type `npm run build` in the root of the repo. This builds the product in the _build/app directory @@ -43,16 +43,15 @@ tfx-cli@0.1.8 /usr/local/lib/node_modules/tfx-cli ├── read@1.0.6 (mute-stream@0.0.5) └── archiver@0.14.4 (buffer-crc32@0.2.5, lazystream@0.1.0, async@0.9.2, readable-stream@1.0.33, tar-stream@1.1.5, lodash@3.2.0, zip-stream@0.5.2, glob@4.3.5) ``` -The product with your local changes is now installed globally. You can now validate your changes as customers would run after installing from npm globally + +The product with your local changes is now installed globally. You can now validate your changes as customers would run after installing from npm globally ## Tracing -Ensure your changes include ample tracing. After installing your changes globally (above), set TFX_TRACE=1 (export on *nix) and run the tool with your changes. Trace output should validate it's doing what you intended, for the reason you intended and provide tracing for others down the road. +Ensure your changes include ample tracing. After installing your changes globally (above), set TFX_TRACE=1 (export on *nix) and run the tool with your changes. Trace output should validate it's doing what you intended, for the reason you intended and provide tracing for others down the road. ## Unit Test If you're changing core parts of the CL engine, ensure unit tests are run and optionally cover the changes you are making. TODO: unit testing details (we use mocha) - pending changes - - diff --git a/docs/extensions.md b/docs/extensions.md index c56698bb..8565cd49 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -8,11 +8,11 @@ To learn more about TFX, its pre-reqs and how to install, see the [readme](../RE ## Package an extension -### Usage +### Extension Create Usage `tfx extension create` -### Arguments +### Extension Create Arguments * `--root`: Root directory. * `--manifest-js`: Manifest in the form of a standard Node.js CommonJS module with an exported function. If present then the manifests and manifest-globs arguments are ignored. @@ -28,11 +28,11 @@ To learn more about TFX, its pre-reqs and how to install, see the [readme](../RE * `--output-path`: Path to write the VSIX. * `--loc-root`: Root of localization hierarchy (see README for more info). -### Examples +### Extension Create Examples -#### Package for a different publisher +#### Package for a different publisher -``` +```bash tfx extension create --publisher mypublisher --manifest-js myextension.config.js --env mode=production ``` @@ -40,7 +40,7 @@ tfx extension create --publisher mypublisher --manifest-js myextension.config.js For example, assume the extension's version is currently `0.4.0` -``` +```bash tfx extension create --rev-version ``` @@ -50,49 +50,48 @@ The version included in the packaged .VSIX and in the source manifest file is no Eventually you will find the need to disambiguate in your manifest contents between development and production builds. Use the `--manifest-js` option to supply a Node.JS CommonJS module and export a function. The function will be invoked with an environment property bag as a parameter, and must return the manifest JSON object. -Environment variables for the property bag are specified with the `--env` command line parameter. These are space separated key-value pairs, e.g. `--env mode=production rootpath="c:\program files" size=large`. +Environment variables for the property bag are specified with the `--env` command line parameter. These are space separated key-value pairs, e.g. `--env mode=production rootpath="c:\program files" size=large`. An example manifest JS file might look like the following: -``` +```js module.exports = (env) => { - let [idPostfix, namePostfix] = (env.mode == "development") ? ["-dev", " [DEV]"] : ["", ""]; - - let manifest = { - manifestVersion: 1, - id: `myextensionidentifier${idPostfix}`, - name: `My Great Extension${namePostfix}`, - ... - contributions: [ - { - id: "mywidgetidentifier", - properties: { - name: `Super Widget${namePostfix}`, - ... - }, - ... - } - ] - } - - if (env.mode == 'development') { - manifest.baseUri = "https://localhost:3000"; - } - - return manifest; + let [idPostfix, namePostfix] = (env.mode == "development") ? ["-dev", " [DEV]"] : ["", ""]; + + let manifest = { + manifestVersion: 1, + id: `myextensionidentifier${idPostfix}`, + name: `My Great Extension${namePostfix}`, + ... + contributions: [ + { + id: "mywidgetidentifier", + properties: { + name: `Super Widget${namePostfix}`, + ... + }, + ... + } + ] + } + + if (env.mode == 'development') { + manifest.baseUri = "https://localhost:3000"; + } + + return manifest; } ``` - ## Publish an extension -### Usage +### Extension Publish Usage -``` +```bash tfx extension publish ``` -### Arguments +### Extension Publish Arguments In addition to all of the `extension create` options, the following options are available for `extension publish`: @@ -100,9 +99,9 @@ In addition to all of the `extension create` options, the following options are * `--share-with`: List of accounts (VSTS) with which to share the extension. * `--nowait-validation`: Use this paramater if you or the pipeline don’t want to wait for the CLI tool to complete. The extension is published and available in the Marketplace only after completion successful validation. -### Example +### Extension Publish Example -``` +```bash tfx extension publish --publisher mypublisher --manifest-js myextension.config.js --env mode=development --share-with myaccount ``` @@ -112,8 +111,6 @@ tfx extension publish --publisher mypublisher --manifest-js myextension.config.j 2. If an Extension with the same ID already exists publisher, the command will attempt to update the extension. 3. When you run the `publish` command, you will be prompted for a Personal Access Token to authenticate to the Marketplace. For more information about obtaining a Personal Access Token, see [Publish from the command line](https://docs.microsoft.com/azure/devops/extend/publish/command-line?view=vsts). - - ## Other commands * `tfx extension install`: Install a Visual Studio Services Extension to a list of VSTS Accounts. @@ -127,4 +124,3 @@ For more details on a specific command, run: ```bash tfx extension {command} --help ``` - diff --git a/docs/workitems.md b/docs/workitems.md index 2c9a4194..28a25417 100644 --- a/docs/workitems.md +++ b/docs/workitems.md @@ -6,62 +6,60 @@ Create, query and view [Work items](https://www.visualstudio.com/en-us/docs/work To learn more about TFX, its pre-reqs and how to install, see the [readme](../README.md) -__Note:__ For work item commands to function when connecting to Team Foundation Server you must login using the collection URL. On VSTS your normal account url will work fine. +__Note:__ For work item commands to function when connecting to Team Foundation Server you must login using the collection URL. On VSTS your normal account url will work fine. Team Foundation Server -> tfx login --service-url http://myServer/DefaultCollection - +> tfx login --service-url Visual Studio Team Services -> tfx login --service-url https://myAccount.VisualStudio.com - +> tfx login --service-url ## Show work item details -### Usage +### WorkItem Show Usage `tfx workitem show` -### Arguments +### WorkItem Show Arguments * `--work-item-id`: Work item id. -### Examples +### WorkItem Show Examples #### Show a work item with id 2 -``` +```bash tfx workitem show --work-item-id 2 ``` ## Query for work items -### Usage +### WorkItem Query Usage -``` +```bash tfx workitem query ``` -### Arguments +### WorkItem Query Arguments * `--query`: WIQL query text. * `--project`: Optional name of the project. This lets you use @Project and @CurrentIteration macros in the query. -### Example +### WorkItem Query Example -``` +```bash tfx workitem query --project MyProject --query "select [system.id], [system.title] from WorkItems" ``` ## Create a work item -### Usage +### WorkItem Create Usage -``` +```bash tfx workitem create ``` -### Arguments +### WorkItem Create Arguments * `--project`: Name of the project. * `--work-item-type`: Work Item type (e.g. Bug). @@ -70,34 +68,35 @@ tfx workitem create * `--description`: Description value * `--values`: JSON object of name/value pairs to set on the Work Item - -### Examples +### WorkItem Create Examples #### Create a work item with a given title -``` + +```bash tfx workitem create --work-item-type Bug --project MyProject --title MyTitle ``` #### Create a work item with values specified from JSON (PowerShell) -``` + +```bash tfx workitem create --work-item-type Bug --project MyProject --values --% {\"system.title\":\"MyTitle\", "system.description\":\"MyDescription\"} ``` #### Create a work item with values specified from JSON (CMD) -``` + +```bash tfx workitem create --work-item-type Bug --project MyProject --values {\"system.title\":\"MyTitle\", "system.description\":\"MyDescription\"} ``` - ## Update a work item -### Usage +### WorkItem Update Usage -``` +```bash tfx workitem update ``` -### Arguments +### WorkItem Update Arguments * `--work-item-id`: Name ID of the work item to update. * `--title`: Title value @@ -105,20 +104,22 @@ tfx workitem update * `--description`: Description value * `--values`: JSON object of name/value pairs to set on the Work Item - -### Examples +### WorkItem Update Examples #### Update a work item with a given title -``` + +```bash tfx workitem update --work-item-id 11 --title MyTitle ``` #### Update a work item with values specified from JSON (PowerShell) -``` + +```bash tfx workitem update --work-item-id 11 --values --% {\"system.title\":\"MyTitle\", "system.description\":\"MyDescription\"} ``` #### Update a work item with values specified from JSON (CMD) -``` + +```bash tfx workitem update --work-item-id 11 --values {\"system.title\":\"MyTitle\", "system.description\":\"MyDescription\"} ```