Backport 2022.02.xx - #8458 adding first commit creation in createpro…

…ject.js script (#8528)  (#8549)

* #8458 adding first commit creation in createproject.js script (#8528)

* #8458 adding first commit creation in createproject.js script

* clean up and improved checkout of branch only if present

* extended project doc with stable branch explanation

* #8458 restore old release since it's not out yet (#8546)

createProject.js

@@ -49,7 +49,7 @@ function doWork(params) {
         name: params.projectName,
         version: params.projectVersion,
         description: params.projectDescription || params.projectName,
-        repository: params.repoURL,
+        repository: params.repoURL || "",
         eslintConfig: {
             "extends": [
                 "@mapstore/eslint-config-mapstore"
@@ -97,6 +97,9 @@ function doWork(params) {
             process.stdout.write('git init\n');
             return project.updateSubmoduleBranch(params.outFolder);
         })
+        .then(() => {
+            return project.createFirstCommit(params.outFolder);
+        })
         .then(() => {
             process.stdout.write('git repo OK!\n');
             process.exit();

docs/developer-guide/project-creation-script.md

@@ -1,10 +1,8 @@
 # Create your own MapStore project
 
-
 !!! note
     From version 2021.02.xx MapStore introduced a new project system. Take a look [here](https://github.com/geosolutions-it/MapStore2/issues/6314) to learn more about the new project system.
 
-
 To create a new MapStore based project you can use the createProject script.
 First of all, if you don't have done it before, clone the MapStore2 repository master branch into a local folder:
 
@@ -18,9 +16,21 @@ Then, move into the folder that has just been created, containing MapStore2:
 cd MapStore2
 ```
 
-Install dependencies for MapStore:
+Choose from which branch you want the mapstore revision to be aligned, we suggest to use latest release or latest stable available (if you know which is)
 
+```sh
+git checkout <stable-branch>
 ```
+
+or
+
+```sh
+git checkout v2022.01.02
+```
+
+Install dependencies for MapStore:
+
+```sh
 npm install
 ```
 
@@ -40,16 +50,21 @@ Note that projectName and outputFolder are mandatory:
 * **gitRepositoryUrl**: full url to the github repository where the project will be published
 * **outputFolder**: folder where the project will be created
 
+Usage:
+
+```sh
+node ./createProject.js standard MyProject "1.0.0" "this is my awesome project" "" ../MY_PROJECT_NAME
+```
+
 At the end of the script execution, the given outputFolder will be populated by all the configuration files needed to start working on the project. Moreover, the local git repository will be initialized and the MapStore sub-module added and downloaded.
 
 If you create a *standard* project, you can customize it editing **js/app.jsx**: look at the comments for hints and the MapStore documentation for more details.
 
 The following steps are:
 
-* npm install to download dependencies
-* npm start to test the project
-* git add / push to publish the initial project on the git repo
-* ./build.sh to build the full war
+* `npm install` to download dependencies
+* `npm start` to test the project
+* `./build.sh` to build the full .war
 
 ## Create a new project type
 
@@ -74,9 +89,11 @@ In addition to static and templates, the following files from the root MapStore
 
 To update MapStore2 version enter the MapStore2 folder and pull desired git version.
 If MapStore2 devDependencies have been changed you can manually update these in the project package.json file or run the script updateDevDeps
+
 ```sh
 npm run updateDevDeps
 ```
+
 The script will automatically copy the devDependencies from MapStore2 package.json to the project package.json file. All the project existing devDependencies will be overwritten.
 
 To sync MapStore2 dependencies just run npm install from project root folder.

docs/developer-guide/release.md

@@ -50,6 +50,7 @@ Replacing:
   - [ ] for geostore, check if [here](https://maven.geo-solutions.it/it/geosolutions/geostore/geostore-webapp/) is present the version specified in the [release calendar 2022](https://github.com/geosolutions-it/MapStore2/wiki/MapStore-Releases-2022)
   - [ ] for http_proxy, check if [here](https://mvnrepository.com/artifact/proxy/http_proxy) is present the version specified in the [release calendar 2022](https://github.com/geosolutions-it/MapStore2/wiki/MapStore-Releases-2022)
 - [ ] If major release (YYYY.XX.00), create a branch `YYYY.XX.xx`  (`xx` is really `xx`, example: 2018.01.xx)
+- [ ] If major release, update the default stable branch used in createProject.js script , in particular the utility/projects/projectLib.js file
 - [ ] If major release, Change [QA Jenkins job](http://build.geosolutionsgroup.com/view/MapStore/job/MapStore/view/MapStore%20QA/job/MapStore2-QA-Build/) to build the new branch, enable the job continuous deploy by updating the `branch` parameter in the build configuration page to `YYYY.XX.xx`
 - [ ] Check version in `package.json`. (as for semantic versioning the major have to be 0 until the npm package has not a stable API).
     - [ ] Take note of current version of mapstore in `package.json` in master branch, it should be in the form 0.x.0

utility/projects/projectLib.js

@@ -22,17 +22,43 @@ const initGit = (outFolder) => {
     const git = require('simple-git')(outFolder);
     return new Promise((resolve, reject) => {
         git.init(() => {
+            process.stdout.write('initializing git repo...\n');
             git.submoduleAdd('https://github.com/geosolutions-it/MapStore2.git', 'MapStore2', (err) => {
                 if (err) {
                     reject(err);
                 } else {
                     resolve();
+                    process.stdout.write('MapStore2 submodule added...\n');
                 }
             });
         });
     });
 };
 
+
+/**
+ * it creates the first commit to be used in git versioning
+ * @return {Promise} the promise to continue the flow of project creation
+ */
+const createFirstCommit = (outFolder) => {
+    process.stdout.write('Creating first commit...\n');
+
+    const git = require('simple-git')(outFolder);
+    return new Promise((resolve, reject) => {
+        git.add(["*"], () => {
+            git.commit('First Commit', (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                    process.stdout.write('First commit created...\n');
+                }
+            });
+        });
+    });
+};
+
+
 /**
  * it does a checkout to a specified folder which in general is rootProject/MapStore2
  * @param {string} outFolder the folder where to apply the checkout
@@ -42,23 +68,37 @@ const updateSubmoduleBranch = (outFolder) => {
     const git = require('simple-git')();
     const gitProjectMs2 = require('simple-git')(`${outFolder}/MapStore2`);
 
+    const stableBranch = "2022.02.xx";
+
     return new Promise((resolve, reject) => {
         try {
             git.branchLocal( (err, data) => {
                 if (err) {
                     reject(err);
                 }
-                process.stdout.write("doing checkout to the branch: " + data.current + "\n");
-                gitProjectMs2.checkout(data.current, null, (error) => {
-                    if (error) {
-                        reject(error);
+                git.fetch("origin", data.current, (er) => {
+                    if (er) {
+                        process.stdout.write(`Warning: It was not possible to checkout to ${data.current} so we checkout to latest stable: ${stableBranch}\n`);
+                        gitProjectMs2.checkout(stableBranch, null, (e) => {
+                            if (e) {
+                                reject(e);
+                            }
+                            process.stdout.write(`checkout to stable branch: ${stableBranch} done\n`);
+                            resolve();
+                        });
+                    } else {
+                        process.stdout.write("doing checkout to the branch: " + data.current + "\n");
+                        gitProjectMs2.checkout(data.current, null, (error) => {
+                            if (error) {
+                                reject(error);
+                            }
+                            resolve();
+                        });
                     }
-                    process.stdout.write("checkout done");
-                    resolve();
                 });
             });
         } catch (e) {
-            process.stdout.write("error");
+            process.stdout.write("error\n");
             process.stdout.write(e);
             reject(e);
         }
@@ -125,5 +165,6 @@ module.exports = {
     createPackageJSON,
     copyTemplates,
     copyStaticFiles,
-    updateSubmoduleBranch
+    updateSubmoduleBranch,
+    createFirstCommit
 };