update README & CHANGELOG, use collapsed blocks (#106)

2018-07-23 14:48:38 +08:00 · 2018-07-23 14:48:38 +08:00 · 4b067505a8
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -2,7 +2,7 @@
 All notable changes to the "vscode-maven" extension will be documented in this file.
 - [Change Log](#change-log)
    - [Unreleased](#unreleased)
-        - [1.0.0](#100)
+        - [0.10.0](#0100)
    - [Released](#released)
        - [0.9.2](#092)
        - [0.9.1](#091)
@ -16,14 +16,13 @@ All notable changes to the "vscode-maven" extension will be documented in this f
    - [Early Versions](#early-versions)

 ## Unreleased
-### 1.0.0
+### 0.10.0
 - Supported to hide Maven explorer view by default. [#51](https://github.com/Microsoft/vscode-maven/issues/51)
 - Started to use a separate terminal for each root folder. [#68](https://github.com/Microsoft/vscode-maven/pull/87)
 - Improved performance of searching for pom.xml [#77](https://github.com/Microsoft/vscode-maven/issues/77)
 - Started to includes Maven archetypes in local catalog when generating projects. [#82](https://github.com/Microsoft/vscode-maven/issues/82)
-(https://github.com/Microsoft/vscode-maven/issues/68)
- Forced to use mvn wrapper as Maven executable file if one is found in root folder. [#84](https://github.com/Microsoft/vscode-maven/issues/84)
- Refined command `maven.history` to re-run historical goals.[#87]
+- Forced to use mvn wrapper as Maven executable file if one is found in root folder, and added a new configuration `maven.executable.preferMavenWrapper` allowing to turn it off. [#84](https://github.com/Microsoft/vscode-maven/issues/84) [#105](https://github.com/Microsoft/vscode-maven/pull/105)
+- Refined command `maven.history` to re-run historical goals.[#87](https://github.com/Microsoft/vscode-maven/issues/87)
 - Some code refactoring and bug fixing.

 ## Released
--- a/README.md
+++ b/README.md
@ -7,60 +7,68 @@

 ## Features

-Maven extension for VS Code. It now reads `pom.xml` in root folder, and provide project structures in sidebar, improving user experience for Java developers who use Maven.
+Maven extension for VS Code. It provides a project explorer and shorcuts to execute maven commands, improving user experience for Java developers who use Maven.
+
+* Support to generate projects from Maven Archetype.
+* Support to generate effective POM.
+* Provide shortcuts to common goals, namely `clean`, `validate`, `compile`, `test`, `package`, `verify`, `install`, `site`, `deploy`.
+* Perserve command history to fast re-run.

-* Effective POM
-* Shortcut to common goals, namely `clean`, `validate`, `compile`, `test`, `package`, `verify`, `install`, `site`, `deploy`.
-* Perserve history of goals to fast re-run long commands(e.g. `mvn clean package -DskipTests -Dcheckstyle.skip`).
-* Can generate projects from Maven Archetype.
-* Support multi-module maven projects.
-* Support VSCode multi-root workspace.

 ## Requirements
+* Java
+* Maven / Maven Wrapper

-Provide Maven executable filepath.
-* By default, `mvn` command is executed directly in the terminal, which requires `mvn` can be found in system envronment `PATH`.
-* If you do not want to add it into `PATH`, you can specify maven executable path in settings:
-    ```
-    {
-        "maven.executable.path": "/some-path-to-maven-home/bin/mvn"
-    }
-    ```
+For troubleshooting, please refer to the page [HERE](Troubleshooting.md).

-## Usage
+## Basic Usage
+<details>
+<summary>Maven Explorer</summary>

-* The extension scans `pom.xml` from each root folder in your workspace recursively, and display all maven projects and their modules in the sidebar.
+The extension scans `pom.xml` in your workspace, and displays all maven projects and their modules in the sidebar.

-    ![Screenshot](images/view_context.png)
+![Screenshot](images/explorer.png)

-* To speed up the searching of maven projects, you can exclude folders in settings:
-    ```
-    {
-        "maven.projects.excludedFolders": [
-            "**/.*",                // exclude hidden folders
-            "**/node_modules",      // exclude node modules to speed up
-            "**/target"             // exclude duplicated pom file in target folder
-        ]
-    }
-    ```
+</details>

-* It perserves history of goals for each project, so you can fast re-run previous long commands, e.g. `mvn <goals> -Dparam1=value1 -Dparam2=value2 -Dparam3=value3 ...` 
+<details>
+<summary>Re-Run Historical Commands</summary>

-    ![Screenshot](images/customGoal.gif)
+It perserves history of goals for each project, so you can fast re-run previous long commands, e.g. `mvn <goals> -Dparam1=value1 -Dparam2=value2 -Dparam3=value3 ...` 
+There are 2 entries for it:
+* Command Palette -> select `Maven: History ...` -> Select a project -> Select command from the history
+* Right-click on a project -> Click `History ...` -> Select command from the history

-* Archetype Related
-    * **Generate from Maven Archetype** The extension loads archetypes listed in local/remote catelog. After selection, the extension fires `mvn archetype:generate -D...` in terminal.
+![Screenshot](images/history.gif)
+</details>
+ 
+<details>
+<summary>Archetype Related</summary>

-    ![Screenshot](images/archetype.gif)
+### Generate from Maven Archetype
+The extension loads archetypes listed in local/remote catelog. After selection, the extension sends `mvn archetype:generate -D...` to terminal.
+There are 2 entries for it:
+* Command Palette -> select `Maven: Generate from Maven Archetype`
+* Right-click on a folder -> Click `Generate from Maven Archetype` 
+
+![Screenshot](images/archetype.gif)
+
+### Update Maven Archetype Catalog
+With following steps, you can update the **local cache** of Maven **remote catelog**. It takes some time to download meta data from Maven central repository.
+
+Command Palette -> select `Maven: Update Maven Archetype Catalog`.
+
+</details>

 ## Additional Configurations

-### JAVA_HOME and Other Environment Variables
+<details>
+<summary>JAVA_HOME and Other Environment Variables</summary>

 This extension executes Maven by opening a terminal session and then calling Maven in that session.
 Maven requires the JAVA_HOME environment variable to be set. Maven will also look for other variables such as MAVEN_OPTS. If you prefer not to set those variables permanently you can configure them, or any other environment variable, in settings:

-```
+```json
 {
    "maven.terminal.customEnv": [
        {
@ -74,12 +82,14 @@ Maven requires the JAVA_HOME environment variable to be set. Maven will also loo
    ]
 }
 ```
+</details>

-### Special Handling for JAVA_HOME
+<details>
+<summary>Special Handling for JAVA_HOME</summary>

 If you have Red Hat's Java Language Support extension installed, then you can specify JAVA_HOME in settings for that extension:

-```
+```json
 {
    "java.home": "C:\\Program Files\\Java\\jdk-9.0.4"      // Red Hat Java Language Support Setting
 }
@ -87,7 +97,7 @@ If you have Red Hat's Java Language Support extension installed, then you can sp

 This extension (Maven for Java) can reuse that setting if you desire:

-```
+```json
 {
    "maven.terminal.useJavaHome": true      // Use the Red Hat Java Language Support Setting for JAVA_HOME
 }
@ -98,16 +108,36 @@ you have other environment variables to set.

 If you have JAVA_HOME configured through the `maven.terminal.customEnv` setting, and also specify to reuse the Red Hat setting, then the value from `maven.terminal.customEnv` will take precedence.

-### Default Options for Maven Command
+</details>
+
+<details>
+<summary>Default Options for Maven Command</summary>
 The usage of maven executable is:
 > usage: mvn [options] [<goal(s)>] [<phase(s)>]

 You can use `maven.executable.options` to specify default **options** for all your maven commands executed in current project.
-```
+```json
 {
    "maven.executable.options": "-o -s ./settings.xml"      // work offline, and use an alternative settings file 
 }
 ```
+</details>
+
+<details>
+<summary>Folder Exclusion for Searching POM Files</summary>
+
+To speed up the searching of maven projects, you can exclude folders in settings:
+
+```json
+{
+    "maven.projects.excludedFolders": [
+        "**/.*",                // exclude hidden folders
+        "**/node_modules",      // exclude node modules to speed up
+        "**/target"             // exclude duplicated pom file in target folder
+    ]
+}
+```
+</details>

 ## Data/Telemetry

--- a/images/explorer.png
+++ b/images/explorer.png
--- a/images/history.gif
+++ b/images/history.gif
--- a/images/view_context.png
+++ b/images/view_context.png
--- a/package-lock.json
+++ b/package-lock.json
@ -115,7 +115,7 @@
        "arr-flatten": {
            "version": "1.1.0",
            "resolved": "https://registry.npmjs.org/arr-flatten/-/arr-flatten-1.1.0.tgz",
-            "integrity": "sha512-L3hKV5R/p5o81R7O02IGnwpDmkp6E982XhtbuwSe3O4qOtMMMtodicASA1Cny2U+aCXcNpml+m4dPsvsJ3jatg==",
+            "integrity": "sha1-NgSLv/TntH4TZkQxbJlmnqWukfE=",
            "dev": true
        },
        "arr-union": {
@ -413,7 +413,7 @@
        "debug": {
            "version": "3.1.0",
            "resolved": "https://registry.npmjs.org/debug/-/debug-3.1.0.tgz",
-            "integrity": "sha512-OX8XqP7/1a9cqkxYw2yXss15f26NKWBpDXQd0/uK/KPqdQhxbPa994hnzjcE2VqQpDslf55723cKPUOGSmMY3g==",
+            "integrity": "sha1-W7WgZyYotkFJVmuhaBnmFRjGcmE=",
            "dev": true,
            "requires": {
                "ms": "2.0.0"
@ -822,7 +822,7 @@
        "growl": {
            "version": "1.10.3",
            "resolved": "https://registry.npmjs.org/growl/-/growl-1.10.3.tgz",
-            "integrity": "sha512-hKlsbA5Vu3xsh1Cg3J7jSmX/WaW6A5oBeqzM88oNbCRQFz+zUaXm6yxS4RVytp1scBoJzSYl4YAEOQIt6O8V1Q==",
+            "integrity": "sha1-GSa6kM8+3+KttJJ/WIC8IsZseQ8=",
            "dev": true
        },
        "gulp-chmod": {
@ -1052,7 +1052,7 @@
                "queue": {
                    "version": "4.4.2",
                    "resolved": "https://registry.npmjs.org/queue/-/queue-4.4.2.tgz",
-                    "integrity": "sha512-fSMRXbwhMwipcDZ08enW2vl+YDmAmhcNcr43sCJL8DIg+CFOsoRLG23ctxA+fwNk1w55SePSiS7oqQQSgQoVJQ==",
+                    "integrity": "sha1-Wpcz2ai4vRs26TS8nFWribKOKcc=",
                    "dev": true,
                    "requires": {
                        "inherits": "~2.0.0"
@ -1749,7 +1749,7 @@
        "regex-cache": {
            "version": "0.4.4",
            "resolved": "https://registry.npmjs.org/regex-cache/-/regex-cache-0.4.4.tgz",
-            "integrity": "sha512-nVIZwtCjkC9YgvWkpM55B5rBhBYRZhAaJbgcFYXXsHnbZ9UZI9nnVWYZpBlCqv9ho2eZryPnWrZGsOdPwVWXWQ==",
+            "integrity": "sha1-db3FiioUls7EihKDW8VMjVYjNt0=",
            "dev": true,
            "requires": {
                "is-equal-shallow": "^0.1.3"
@ -1825,7 +1825,7 @@
        "rimraf": {
            "version": "2.6.2",
            "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.6.2.tgz",
-            "integrity": "sha512-lreewLK/BlghmxtfH36YYVg1i8IAce4TI7oao75I1g245+6BctqTVQiBP3YUJ9C6DQOXJmkYR9X9fCLtCOJc5w==",
+            "integrity": "sha1-LtgVDSShbqhlHm1u8PR8QVjOejY=",
            "dev": true,
            "requires": {
                "glob": "^7.0.5"
@ -1855,7 +1855,7 @@
        "source-map": {
            "version": "0.6.1",
            "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
-            "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+            "integrity": "sha1-dHIq8y6WFOnCh6jQu95IteLxomM=",
            "dev": true
        },
        "source-map-support": {