Merge pull request #86 v2.0.0

Release v2!!!!!

Author: brianbunke

.gitignore

@@ -2,6 +2,34 @@
 *.ini
 *.conf
 *.config
+config.xml
 
-# Ignore Environment files
-.env*
+# Ignore all files beginning with a dot (.)
+.*
+# except for git files
+!.gitattributes
+!.gitignore
+!.github/
+
+# Ignore Release directory generated by local builds
+Release/
+Tools/
+ConfluencePS/en-US/
+TestResult.xml
+
+#######
+# Excerpts from https://www.gitignore.io
+#######
+
+### OSX ###
+.DS_Store
+.AppleDouble
+.LSOverride
+
+### Windows ###
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini

.vscode/settings.json

@@ -5,5 +5,12 @@
     "files.trimTrailingWhitespace": true,
     "files.insertFinalNewline": true,
     "editor.tabSize": 4,
-    "powershell.scriptAnalysis.settingsPath": "PSScriptAnalyzerSettings.psd1"
+    "powershell.scriptAnalysis.settingsPath": "PSScriptAnalyzerSettings.psd1",
+    "[markdown]": {
+        "editor.wordwrap": "on",
+        "editor.renderWhitespace": "all",
+        "editor.acceptSuggestionOnEnter": false,
+        "editor.rulers": [80],
+        "editor.trimAutoWhitespace": false
+    },
 }

.vscode/tasks.json

@@ -1,63 +1,56 @@
-// A task runner that invokes Pester to run all Pester tests under the
-// current workspace folder.
-
-// NOTE: This Pester task runner requires an updated version of Pester (>=3.4.0)
-// in order for the problemMatcher to find failed test information (message, line, file).
-// If you don't have that version, you can update Pester from the PSGallery like so:
-//
-// PS C:\> Update-Module Pester
-//
-// If that gives an error like:
-// "Module 'Pester' was not installed by using Install-Module, so it cannot be updated."
-// then execute:
-//
-// PS C:\> Install-Module Pester -Scope CurrentUser -Force
-//
-
 // Available variables which can be used inside of strings.
 // ${workspaceRoot}: the root folder of the team
 // ${file}: the current opened file
+// ${relativeFile}: the current opened file relative to workspaceRoot
 // ${fileBasename}: the current opened file's basename
 // ${fileDirname}: the current opened file's dirname
 // ${fileExtname}: the current opened file's extension
 // ${cwd}: the current working directory of the spawned process
-
 {
-    "version": "0.1.0",
-
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
     // Start PowerShell
-    "command": "${env.windir}\\sysnative\\windowspowershell\\v1.0\\PowerShell.exe",
-
-    // The command is a shell script
-    "isShellCommand": true,
-
+    "windows": {
+        "command": "${env:windir}\\sysnative\\windowspowershell\\v1.0\\PowerShell.exe",
+        "args": [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass"
+        ]
+    },
+    "linux": {
+        "command": "/usr/bin/powershell",
+        "args": [
+            "-NoProfile"
+        ]
+    },
+    "osx": {
+        "command": "/usr/local/bin/powershell",
+        "args": [
+            "-NoProfile"
+        ]
+    },
     // Show the output window always
     "showOutput": "always",
-
-    "args": [
-        "-NoProfile", "-ExecutionPolicy", "Bypass",
-        "if (Test-Path '${workspaceRoot}\\.env.ps1') {. '${workspaceRoot}\\.env.ps1'}; Write-Host 'Invoking Pester...'; Invoke-Pester -PesterOption @{IncludeVSCodeMarker=$true};",
-        "Invoke-Command { Write-Host \"Completed all tasks in task runner: $($args[0])\" } -args"
-    ],
-
     // Associate with test task runner
     "tasks": [{
-        "taskName": "Pester",
-        "isTestCommand": true,
-        "problemMatcher": [{
-            "owner": "powershell",
-            "fileLocation": ["absolute"],
-            "severity": "error",
-            "pattern": [{
-                    "regexp": "^\\s*(\\[-\\]\\s*.*?)(\\d+)ms\\s*$",
-                    "message": 1
-                },
-                {
-                    "regexp": "^\\s+at\\s+[^,]+,\\s*(.*?):\\s+line\\s+(\\d+)$",
-                    "file": 1,
-                    "line": 2
-                }
+            "taskName": "Build Help",
+            "suppressTaskName": true,
+            "args": [
+                "Write-Host 'Invoking platyPS'; New-ExternalHelp -Path .\\docs\\en-US -OutputPath .\\ConfluencePS\\en-US -Force;",
+                "Invoke-Command { Write-Host 'Completed Build task in task runner.' }"
             ]
-        }]
-    }]
+        },
+        {
+            "taskName": "Test",
+            "suppressTaskName": true,
+            "isTestCommand": true,
+            "args": [
+                "Write-Host 'Invoking Pester'; Invoke-Pester -PesterOption @{IncludeVSCodeMarker=$true};",
+                "Invoke-Command { Write-Host 'Completed Test task in task runner.' }"
+            ],
+            "problemMatcher": "$pester"
+        }
+    ]
 }

CHANGELOG.md

@@ -0,0 +1,106 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [2.0.0] - 2017-08-17
+A new major version! ConfluencePS has been totally refactored to introduce new features and greatly improve efficiency.
+
+"A new major version" means limited older functionality was intentionally broken. In addition, there are a ton of good changes, so some big picture notes first:
+
+- All functions changed from "Wiki" prefix to "Confluence", like `Get-ConfluencePage`
+  - But the module accommodates for any prefix you want, e.g. `Import-Module ConfluencePS -Prefix Wiki`
+- Functions changed or removed:
+  - `Get-WikiLabelApplied` [removed; functionality added to `Get-ConfluencePage -Label foo`]
+  - `Get-WikiPageLabel` > `Get-ConfluenceLabel`
+  - `New-WikiLabel` > `Add-ConfluenceLabel`
+- `Get-*` functions now support paging, and defining your preferred page size
+- `-Limit` and `-Expand` parameters were removed from functions
+  - With paging implementation, modifying the returned object limit isn't necessary
+  - And allows for richer objects to be returned by default
+- `-ApiUri` and `-Credential` parameters added to every function
+  - This is useful if you have more than one Confluence instance
+  - `Set-ConfluenceInfo` now defines `ApiUri` and `Credential` defaults for the current session
+  - And you can override any single function:
+  - `Get-ConfluenceSpace -ApiUri 'https://wiki2.example.com' -Credential (Get-Credential)`
+- All functions now output custom object types, like `[ConfluencePS.Page]`
+  - Allows for returning more object properties...
+  - ...and only displaying the most relevant in the default output
+  - Also enables a much improved pipeline flow
+  - This behavior removed the need for the `-Expand` parameter
+- Private functions are leveraged heavily to reduce repeat code
+  - `Invoke-Method` is the most prominent example
+
+If you like drinking from the firehose, here's [everything we closed for 2.0], because we probably forgot to list something here. Otherwise, read on for summarized details.
+
+### Added
+- All `Get-*` functions now support paging
+- `-ApiUri` and `-Credential` parameters added to functions
+  - `Set-ConfluenceInfo` behavior is mostly unchanged (see below)
+- Objects returned are now custom typed, like `[ConfluencePS.Page]`
+  - Try piping ConfluencePS objects into `Format-List *` to see all properties
+
+### Changed
+- Function prefix defaults to "Confluence" instead of "Wiki" (`Get-ConfluenceSpace`)
+  - If you like "Wiki", you can `Import-Module ConfluencePS -Prefix Wiki`
+- `Add-ConfluenceLabel`
+  - Name used to be `New-WikiLabel`
+  - The "Add" verb better reflects the function's behavior
+- `Get-ConfluenceChildPage`
+  - Default behavior returns only immediate child pages. Which also means...
+  - Added `-Recurse` to return all pages below the given page, not just immediate child objects
+    - NOTE: Recurse is not available in on-prem installs right now, only Atlassian cloud instances
+  - `-ParentID` > `-PageID`
+- `Get-ConfluenceLabel`
+  - Name used to be `Get-WikiPageLabel`
+  - Now returns `[ConfluencePS.ContentLabelSet]` objects
+    - Which are relationships of `[ConfluencePS.Label]` & `[ConfluencePS.Page]` objects
+- `Get-ConfluencePage`
+  - `Get-ConfluencePage` (with no parameters) doesn't work anymore
+    - With paging supported, this would be a ton of pages
+    - `Get-ConfluenceSpace | Get-ConfluencePage` still works, if you really need it
+  - Now returns `[ConfluencePS.Page]` objects
+  - New `-Label` parameter filters returned pages by applied label(s)
+  - New `-Space` parameter accepts Space objects
+- `Get-ConfluenceSpace`
+  - Now returns `[ConfluencePS.Space]` objects
+  - `-Key` renamed to `-SpaceKey` ("Key" still works as an alias)
+  - `-Name` parameter removed
+- `New-ConfluencePage`
+  - New `-Parent` parameter accepts Page objects
+  - New `-Space` parameter accepts Space objects
+- `New-ConfluenceSpace`
+  - `-Key` renamed to `-SpaceKey` ("Key" still works as an alias)
+- `Set-ConfluenceInfo`
+  - Now adds the URI/Credential to `$PSDefaultParameterValues`
+    - `-ApiUri` & `-Credential` parameters now exist on every function
+    - `Set-ConfluenceInfo` defines their defaults for the current session
+    - Meaning they could still be overwritten on any single command
+  - No longer automatically prompts for credentials if `-Credential` is absent
+    - Allows for anonymous authentication to public instances
+  - New `-PromptCredentials` parameter displays a `Get-Credential` dialog while connecting
+  - New `-PageSize` parameter optionally defines default page size for the session
+- `Set-ConfluencePage`
+  - Now returns `[ConfluencePS.Page]` objects
+  - `-CurrentVersion` parameter removed (determined and incremented automatically now)
+  - New `-Parent` parameter accepts Page objects
+
+### Removed
+- `-Limit` and `-Expand` parameters
+  - `Get-*` function paging removes the need for fiddling with returned object limits
+  - Custom object types hold relevant properties, removing the need to manually "expand" results
+- `Get-WikiLabelApplied`
+  - Functionality replaced with `Get-ConfluencePage -Label foo`
+
+### Much ❤
+[@lipkau](https://github.com/lipkau) refactored the entire module, and is the only reason `2.0` is a reality. In short, he is amazing. Thank you!
+
+
+## [1.0.0-69] - 2016-11-28
+No changelog available for version `1.0` of ConfluencePS. `1.0` was created in late 2015. Version `.69` was published to the PowerShell Gallery in Nov 2016, and it remained unchanged until `2.0`. If you're looking for things that changed prior to `2.0`...sorry, but these probably aren't the droids you're looking for. :)
+
+
+
+[everything we closed for 2.0]: https://github.com/AtlassianPS/ConfluencePS/issues?utf8=%E2%9C%93&q=closed%3A2017-04-01..2017-08-17