more README

Author: JohannesHoppe

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 John Doe
+Copyright (c) 2019 Minko Gechev, Johannes Hoppe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -2,37 +2,48 @@
 
 ## About
 
-This is a sample project that helps you to implement your own __deployment builder__ for the Angular CLI.
+This is a sample project that helps you to implement your own __deployment builder__ (`ng deploy`) for the Angular CLI.
 The groundwork of this starter was provided by Minko Gechev's [ngx-gh project](https://github.com/mgechev/ngx-gh).
 
 This project has the following purposes:
 
 1. To promote the adoption of `ng deploy`.
-2. To clarify various questions and to standardise the experience of the various builders.
+2. To clarify various questions and to standardise the experience of the various builders.  
+
+**We hope for an inspiring discussion, pull requests and questions.**
 
 ## Essential considerations
 
 These rules are open for discussion, of course.
 
-### 1. A deployment builder should always compile the project before the deployment
+### 1. A deployment builder must always compile the project before the deployment
 
 To reduce the chances to deploy corrupted assets, it's important to build the app right before deploying it. ([source](https://github.com/angular-schule/website-articles/pull/3#discussion_r315802100))
 
+**Current state:**  
 Currently there are existing deployment builders that only build in production mode.
 This might be not enough.
 There is also the approach not to perform the build step at all.
 
-**Our suggestion:**
-By default, a deployment builder compiles in `production` mode, but you can configure an other coniguration using the option `--configuration`.
+**Our suggestion:**  
+By default, a deployment builder **shall** compile in `production` mode, but it **should** be possible to override the default coniguration using the option `--configuration`.
+
+Discussion: https://github.com/angular-schule/ngx-deploy-starter/issues/1
+
+### 2. A deployment builder should have an interactive prompts after the "ng add".
+
+To make it easier for the end user to get started, a deployment builder **should** ask for all the mandatory questions immediately after the `ng add`.
+The data should be persisted in the `angular.json` file.
 
-### 2. A deployment builder should have an interactive wizard after the "ng add".
+**Note:**  
+This feature is not implemented for this starter yet, but we are looking forward to your support.
 
-This wizard should ask all necessary questions and should persist the answers in the `angular.json` file.
-This feature is not implemented yet, but we are looking forward to your feedback.
+Discussion: https://github.com/angular-schule/ngx-deploy-starter/issues/2
 
-### 2. More to come
+### 3. More to come
 
-What's bothers you about this example? We appreciate your feedback!
+What's bothers you about this example?
+We appreciate your [feedback](https://github.com/angular-schule/ngx-deploy-starter/issues)!
 
 
 ## How to make your own deploy builder
@@ -41,7 +52,8 @@ What's bothers you about this example? We appreciate your feedback!
 2. adjust the `package.json`
 3. search and replace for the string `ngx-deploy-starter` and choose your own name.
 4. search and replace for the string `to the file system` and name your deploy target.
-5. add your deployment code to `src/engine/engine.ts`x
+5. add your deployment code to `src/engine/engine.ts`, take care of the tests
+6. follow the instructions from the [contributors README](docs/README_contributors.md) for build, test and publishing.
 
 
 You are free to customise this project according to your needs.

docs/README_contributors.md

@@ -12,15 +12,15 @@ npm test
 ```
 
 
-## Local development <a name="local-dev"></a>
+## Local development
 
 If you want to try the latest package locally without installing it from NPM, use the following instructions.
 This may be useful when you want to try the latest non-published version of this library or you want to make a contribution.
 
 Follow the instructions for [checking and updating the Angular CLI version](#angular-cli) and then link the package.
 
 
-### 1. Angular CLI <a name="angular-cli"></a>
+### 1. Angular CLI
 
 1. Install the next version of the Angular CLI.
 
@@ -71,7 +71,7 @@ Use the following instructions to make `ngx-deploy-starter` available locally vi
 Read more about the `link` feature in the [official NPM documentation](https://docs.npmjs.com/cli/link).
 
 
-### 3. Adding to an Angular project -- ng add <a name="local-dev-add"></a>
+### 3. Adding to an Angular project -- ng add
 
 Once you have completed the previous steps to `npm link` the local copy of `ngx-deploy-starter`, follow these steps to use it in a local Angular project.
 
@@ -102,7 +102,7 @@ Once you have completed the previous steps to `npm link` the local copy of `ngx-
 5. You can remove the link later by running `npm unlink`
 
 
-### 4. Testing <a name="testing"></a>
+### 4. Testing
 
 Testing is done with [Jest](https://jestjs.io/).
 To run the tests:
@@ -114,20 +114,11 @@ npm test
 
 
 
-
-
-## Testing the standalone CLI
-
-To quickly test the file `engine.ts` directly, the standalone mode is the best option.
-Use VSCode and debug the task `Launch Standalone Program`.
-
-
 ## Publish to NPM
 
 ```
 cd ngx-deploy-starter/src
 npm run build
 npm run test
 npm publish dist
-npm dist-tag add [email protected] next
 ```

src/README.md

@@ -22,13 +22,6 @@ ng deploy [options]
 
 The following options are also available.
 
-#### --target-dir
- * __optional__
- * Default: `~/example-folder` (string)
- * Example:
-    * `ng deploy` -- App is "deployed" to the example folder (if existing)
-    * `ng deploy --target-/var/www/html` -- App is "deployed" to another folder
-
 
 #### --configuration
  * __optional__
@@ -41,3 +34,25 @@ A named build target, as specified in the `configurations` section of `angular.j
 Each named target is accompanied by a configuration of option defaults for that target.
 Same as `ng build --configuration=XXX`.
 
+> **This is a proposal from [RFC #1](https://github.com/angular-schule/ngx-deploy-starter/issues/1).**
+
+#### --target-dir
+ * __optional__
+ * Default: `~/example-folder` (string)
+ * Example:
+    * `ng deploy` -- App is "deployed" to the example folder (if existing)
+    * `ng deploy --target-/var/www/html` -- App is "deployed" to another folder
+
+> **This is one of the options you can freely choose according to your needs.**
+
+#### --base-href <a name="base-href"></a>
+ * __optional__
+ * Default: `undefined` (string)
+ * Example:
+    * `ng deploy` -- `<base href="/">` remains unchanged in your `index.html`
+    * `ng deploy --base-href=/the-repositoryname/` -- `<base href="/the-repositoryname/">` is added to your `index.html`
+
+Specifies the base URL for the application being built.
+Same as `ng build --base-href=/XXX/`
+
+> **This is an example how to override the workspace set of options.**

src/deploy/schema.json

@@ -3,13 +3,17 @@
   "title": "schema",
   "description": "Deployment of Angular CLI applications to GitHub pages (ngx-deploy-starter)",
   "properties": {
+    "baseHref": {
+      "type": "string",
+      "description": "This is an example how to override the workspace set of options. --- Base url for the application being built. Same as `ng build --base-href=/XXX/`."
+    },
     "configuration": {
       "type": "string",
-      "description": "A named build target, as specified in the `configurations` section of angular.json. Each named target is accompanied by a configuration of option defaults for that target. Same as `ng build --configuration=XXX`."
+      "description": "This is a proposal from RFC #1. --- A named build target, as specified in the `configurations` section of angular.json. Each named target is accompanied by a configuration of option defaults for that target. Same as `ng build --configuration=XXX`."
     },
     "targetDir": {
       "type": "string",
-      "description": "Only for demonstration: we will 'deploy' to this folder."
+      "description": "This is one of the options you can freely choose according to your needs. --- We will 'deploy' to this folder."
     }
   }
 }