lots of cool updates to the template including a test harness

commandbox-modules · Mar 16, 2022 · 480f6b7 · 480f6b7
1 parent aa17842
commit 480f6b7
Show file tree

Hide file tree

Showing 9 changed files with 164 additions and 178 deletions.
diff --git a/.github/FUNDING.YML b/.github/FUNDING.YML
@@ -0,0 +1 @@
+patreon: ortussolutions
diff --git a/ModuleConfig.cfc b/ModuleConfig.cfc
@@ -1,28 +1,26 @@
 /**
-*********************************************************************************
-* Copyright Since 2014 CommandBox by Ortus Solutions, Corp
-* www.coldbox.org | www.ortussolutions.com
-********************************************************************************
-* @author
-*/
+ * Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp
+ * www.ortussolutions.com
+ * ---
+ * @author
+ */
 component {
 
-	this.cfmapping = "@module_slug@";
+	this.cfmapping      = "@module_slug@";
 	this.modelNamespace = "@module_slug@";
 
-	function configure() {
-
-		settings = {
-		}
+	function configure(){
+		settings = {}
 
 		interceptors = []
 	}
 
 	function onLoad(){
-		//log.info('Module loaded successfully.' );
+		// log.info('Module loaded successfully.' );
 	}
 
 	function onUnLoad(){
-		//log.info('Module unloaded successfully.' );
+		// log.info('Module unloaded successfully.' );
 	}
+
 }
diff --git a/README.md b/README.md
@@ -1,36 +1,13 @@
 # Ortus CommandBox Module Template
 
-This template can be used to create Ortus based ColdBox Modules.  To configure the template for your module, just clone this repository and discard the `.git` folder.  Create your own repository with your own `module slug` and init the repository as follows:
+This template can be used to create CommandBox Modules with automation, testing and much more.  To use, just click the `Use this Template` button in the github repository: https://github.com/commandbox-modules/commandbox-template and run the setup task from where you cloned it.
 
 ```bash
-mkdir myModule
-cd mymodule
-git clone [email protected]:commandbox-modules/commandbox-template.git
-rm -Rf .git
-git init
-box task run taskFile=build/setupTemplate
+box run-script setupTemplate
 ```
 
 The `setupTemplate` task will ask you for your module name, id and description and configure the template for you! Enjoy!
 
-## LICENSE
-
-Apache License, Version 2.0.
-
-## SYSTEM REQUIREMENTS
-
-- CommandBox 5.1+
-
-## Installation
-
-Install the commands via CommandBox like so:
-
-```bash
-box install @module_slug@
-```
-
-----
-
 # Module Template
 
 This is a CommandBox based module template.  Here are some of the tokens to replace to make it your own:
@@ -39,33 +16,48 @@ This is a CommandBox based module template.  Here are some of the tokens to repl
 - `@module_slug@` - The module slug identifier
 - `@module_description@` - Module short description
 
-## Layout
+## Directory Layout
 
 Here is a description of the layout of a CommandBox module:
 
 - `.github` - Github workflows
-- `build` - Hosts a `Build.cfc` task runner that builds, tests and documents your module. You will have to add your tests via the `runRTests()` method.
+- `build/Build.cfc` - Task that builds, tests and documents your module.
+- `build/Tests.cfc` - This is your test harness. Add all your commands to test inside the `run()` method
 - `commands` - The commands for you to implement.
-- `changelog.md` - Your changelog file
+- `.cfformat.json` - A CFFormat using the Ortus Standards
+- `.cflintrc` - A CFLint configuration file according to Ortus Standards
+- `.editorconfig` - Smooth consistency between editors
+- `.gitattributes` - Git attributes
+- `.gitignore` - Basic ignores. Modify as needed.
+- `.markdownlint.json` - A linting file for markdown docs
+- `box.json` - The box.json for YOUR module.  Modify as needed.
+- `changelog.md` - A nice semantic parselog changelog tracking file
+- `ModuleConfig.cfc` - Your module's configuration. Modify as needed.
+- `readme.md` - Your module's readme. Modify as needed.
+
+## Package Scripts
+
+Your module template comes with several useful package scripts:
+
+| Script       		| Description |
+|-------------------|-----------|
+| `build:docs` 		| Build the API docs using DocBox |
+| `build:module` 	| Build the module distribution with Docs and tests |
+| `runTests` 		| Run the test task: `build/Tests.cfc` |
+| `setupTemplate` 	| Setup the template when cloning |
+| `format:check` 	| Check the formmating of your code |
+| `format:watch` 	| Watch for changes and format your code automatically |
+| `format` 			| Format your code|
+| `release` 		| Runs the `build/release.boxr` recipe, which merges `development` into `master`, tags, auto bumps and pushes to your repo |
 
 ## Github Actions Automation
 
 The github actions will clone, test, package, deploy your module to ForgeBox and the Ortus S3 accounts for API Docs and Artifacts.  So please make sure the following environment variables are set in your repository. ** Please note that most of them are already defined at the org level **
 
-* `FORGEBOX_TOKEN` - The Ortus ForgeBox API Token
-* `AWS_ACCESS_KEY` - The travis user S3 account
-* `AWS_ACCESS_SECRET` - The travis secret S3
-
-> Please contact the admins in the `#infrastructure` channel for these credentials if needed
-
-
-----
-
-
-# CREDITS & CONTRIBUTIONS
-
-I THANK GOD FOR HIS WISDOM FOR THIS PROJECT
+- `FORGEBOX_TOKEN` - The Ortus ForgeBox API Token
+- `AWS_ACCESS_KEY` - The travis user S3 account
+- `AWS_ACCESS_SECRET` - The travis secret S3
 
-## THE DAILY BREAD
+## API Docs
 
-"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12
+The build task will take care of building API Docs using DocBox for you but **ONLY** for the `commands` folder in your module.  If you want to document more then make sure you modify the `build/Build.cfc` task.
diff --git a/box.json b/box.json
@@ -1,16 +1,16 @@
 {
-    "name":"@module_name@",
+    "name":"@MODULE_NAME@",
     "version":"1.0.0",
-    "location":"https://downloads.ortussolutions.com/ortussolutions/commandbox-modules/@module_slug@/@build.version@/@module_slug@[email protected]@.zip",
-    "slug":"@module_slug@",
+    "location":"https://downloads.ortussolutions.com/ortussolutions/commandbox-modules/@MODULE_SLUG@/@build.version@/@MODULE_SLUG@[email protected]@.zip",
+    "slug":"@MODULE_SLUG@",
     "author":"Ortus Solutions, Corp",
-    "homepage":"https://www.forgebox.io/view/@module_slug@",
+    "homepage":"https://www.forgebox.io/view/@MODULE_SLUG@",
     "documentation":"https://github.com/commandbox-modules/wiki",
     "repository":{
         "type":"git",
-        "url":"https://github.com/commandbox-modules/@module_slug@"
+        "url":"https://github.com/commandbox-modules/@MODULE_SLUG@"
     },
-    "bugs":"https://github.com/commandbox-modules/@module_slug@/issues",
+    "bugs":"https://github.com/commandbox-modules/@MODULE_SLUG@/issues",
     "shortDescription":"@module_description@",
     "type":"commandbox-modules",
     "keywords": [],
@@ -23,16 +23,26 @@
     "contributors":[
     ],
 	"devDependencies":{
+		"commandbox-cfformat":"*",
         "commandbox-docbox":"*"
     },
     "dependencies":{
     },
     "installPaths":{
     },
+	"ignore":[
+        "**/.*",
+        "test-harness",
+		"/server*.json"
+    ],
     "scripts":{
-        "release":"recipe build/release.boxr",
-        "format":"cfformat run commands,build,ModuleConfig.cfc --overwrite",
+		"build:docs":"task run taskFile=build/Build.cfc target=docs :projectName=`package show slug` :version=`package show version`",
+		"build:module":"task run taskFile=build/Build.cfc :projectName=`package show slug` :version=`package show version`",
+		"runTests" : "task run taskFile=build/Build.cfc target=runTests :projectName=`package show slug` :version=`package show version`",
+		"setupTemplate": "task run taskFile=build/SetupTemplate.cfc",
+        "format:check":"cfformat check commands,build,ModuleConfig.cfc",
         "format:watch":"cfformat watch commands,build,ModuleConfig.cfc",
-        "format:check":"cfformat check commands,build,ModuleConfig.cfc"
+        "format":"cfformat run commands,build,ModuleConfig.cfc --overwrite",
+        "release":"recipe build/release.boxr"
     }
-}
+}
diff --git a/build/Build.cfc b/build/Build.cfc
@@ -14,6 +14,7 @@ component {
 		variables.buildDir     = cwd & "/.tmp";
 		variables.apiDocsURL   = "http://localhost:60299/apidocs/";
 		variables.testRunner   = "http://localhost:60299/tests/runner.cfm";
+		variables.exportsDir   = "";
 
 		// Source Excludes Not Added to final binary: You can use REGEX
 		variables.excludes = [
@@ -36,10 +37,7 @@ component {
 		} );
 
 		// Create Project Dependency Mappings
-		//fileSystemUtil.createMapping(
-		//	"contentbox-cli",
-		//	variables.cwd
-		//);
+		fileSystemUtil.createMapping( "@module_name@", variables.cwd );
 
 		return this;
 	}
@@ -78,7 +76,7 @@ component {
 		latestChangelog();
 
 		// Finalize Message
-		print
+		variables.print
 			.line()
 			.boldMagentaLine( "Build Process is done! Enjoy your build!" )
 			.toConsole();
@@ -88,11 +86,43 @@ component {
 	 * Run the test suites
 	 */
 	function runTests(){
+		variables.print
+			.line()
+			.boldGreenLine( "------------------------------------------------" )
+			.boldGreenLine( "Starting to execute your tests..." )
+			.boldGreenLine( "------------------------------------------------" )
+
+		var sTime = getTickCount();
+
+		variables.print
+			.line()
+			.boldMagentaLine( "Linking your module..." )
+			.toConsole();
+		command( "link" ).run();
+
 		// Tests First, if they fail then exit
+		try {
+			// Run your tests via the `command()` options here.
+			command( "task run build/Tests.cfc" ).run();
+		} finally {
+			// Unlink your module
+			variables.print
+				.line()
+				.boldMagentaLine( "Unlinking your module..." )
+				.toConsole();
+			command( "unlink" ).run();
+		}
 
 		// Check Exit Code?
 		if ( shell.getExitCode() ) {
 			return error( "X Cannot continue building, tests failed!" );
+		} else {
+			variables.print
+				.line()
+				.boldGreenLine( "------------------------------------------------" )
+				.boldGreenLine( "All tests passed in #getTickCount() - sTime#ms! Ready to go, great job!" )
+				.boldGreenLine( "------------------------------------------------" )
+				.toConsole();
 		}
 	}
 
@@ -111,15 +141,18 @@ component {
 		branch  = "development"
 	){
 		// Build Notice ID
-		print.line()
+		variables.print
+			.line()
 			.boldMagentaLine(
 				"+ Building #arguments.projectName# v#arguments.version#+#arguments.buildID# from #cwd# using the #arguments.branch# branch."
 			)
 			.toConsole();
 
 		// Prepare exports directory
-		variables.exportsDir = variables.artifactsDir & "/#projectName#/#arguments.version#";
-		directoryCreate( variables.exportsDir, true, true );
+		seedExportDir(
+			arguments.projectName,
+			arguments.version
+		);
 
 		// Project Build Dir
 		variables.projectBuildDir = variables.buildDir & "/#projectName#";
@@ -189,13 +222,21 @@ component {
 	){
 		// Generate Docs
 		print.greenLine( "+ Generating API Docs, please wait..." ).toConsole();
+
+		// Create docs output dir
 		directoryCreate( arguments.outputDir, true, true );
+		// Seed exports dir
+		seedExportDir(
+			arguments.projectName,
+			arguments.version
+		);
 
+		// Generate the docs
 		command( "docbox generate" )
 			.params(
 				"source"                = "commands",
-				"excludes"				= "",
-				"mapping"               = "contentbox-cli",
+				"excludes"              = "",
+				"mapping"               = "@module_name@",
 				"strategy-projectTitle" = "#arguments.projectName# v#arguments.version#",
 				"strategy-outputDir"    = arguments.outputDir
 			)
@@ -229,7 +270,8 @@ component {
 			fileRead( variables.cwd & "changelog.md" ).split( "----" )[ 2 ].trim() & chr( 13 ) & chr( 10 )
 		);
 
-		print.greenBoldLine( "  √ Latest changelog file created at `changelog-latest.md`" )
+		variables.print
+			.greenBoldLine( "  √ Latest changelog file created at `changelog-latest.md`" )
 			.line()
 			.line( fileRead( variables.cwd & "changelog-latest.md" ) );
 	}
@@ -300,4 +342,18 @@ component {
 		return ( createObject( "java", "java.lang.System" ).getProperty( "cfml.cli.exitCode" ) ?: 0 );
 	}
 
+	/**
+	 * Seed the export directory variable
+	 */
+	private function seedExportDir(
+		required projectName,
+		required version
+	){
+		if ( !len( variables.exportsDir ) ) {
+			// Init export directory
+			variables.exportsDir = variables.artifactsDir & "/#arguments.projectName#/#arguments.version#";
+			directoryCreate( variables.exportsDir, true, true );
+		}
+	}
+
 }