Merge branch 'docs/base'

CONTRIBUTING.md

@@ -2,31 +2,44 @@
 If you'd like to contribute to Blackrik, please make sure you follow our [guidelines](#guidelines).
 
 # Guidelines
+To make development easier, there are a few rules that should be respected (yeah I know... rules 😒 but without them it would turn into an anarchy).
+
+Just stick to our [workflow](#Workflow) and you should be fine.
 
 ## Workflow
 Before you start, make sure there is no open issue that proposes your feature or fix (or whatever).  
 If there is already an issue that kinda fits but does not exactly match your proposal, hook into the discussion.
 
 Otherwise
 1. Create a new [issue](https://guides.github.com/features/issues/) so your proposal can be discussed first.
-2. Create a new [branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches) of this repository to work in.
+2. Create a new [branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches) of this repository to work in (see [branches](#Branches) for naming).
 3. Implement your feature or fix or enhancement.
-4. Add (or update) [tests](#testing) if needed.
-5. Make sure your code complies with our [codestyle](#codestyle): `$ npx eslint .`.
+4. Make sure your code complies with our [codestyle](#codestyle): `$ npx eslint .`.
+5. Add (or update) [tests](#testing) if needed.
 6. Make sure all [tests](#testing) pass: `$ npm run test`.
 7. Commit all changes to your branch (from step 2) and write useful commit messages for others to be able to undestand what changed.
 8. Create a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) (PR) to inform others about your changes.
 9. Your PR will be reviewed. If changes are requested, simply commit these to your branch.
 10. After everything's right, someone will merge your branch into the master branch.
 
+## Branches
+When creating a new branch use the pattern `<category>/<topic>` or `<category>/<issue>/<topic>` for its name. Category may be one of the following `feature`, `bugfix`, `hotfix`, `docs`, ...  
+While the topic describes what exactly the branch is about.  
+You may add an issue id in-between e.g. `feature/42/my-feature` if issue #42 belongs to "my-feature".
+
+Try to keep the name short e.g. instead of:  
+`bugfix/there-is-a-bug-where-the-api-explodes-when-calling-specific-routes`  
+just use:  
+`bugfix/api-explosion`
+
 ## Codestyle
-We use [ESLint](https://eslint.org/) to make sure the code has a constant style. That style is described via rules inside the [.eslintrc.js](https://github.com/wesone/blackrik/blob/master/.eslintrc.js) file.
+We use [ESLint](https://eslint.org/) to make sure the code has a consistent style. That style is described via rules inside the [.eslintrc.js](https://github.com/wesone/blackrik/blob/master/.eslintrc.js) file.
 
 To test if all rules are satisfied run `$ npx eslint .` from the project's root directory (or `$ npx eslint <dir>`).  
 ESLint can fix some problems automatically if you use `$ npx eslint --fix .` but be advised that the `--fix` flag might manipulate your code.
 
 ### Naming
-Please use descriptive names (for functions, parameters, classes, variables, ...) in [camel case](https://en.wikipedia.org/wiki/Camel_case) and avoid abbreviations when possible.
+Please use descriptive names (for functions, parameters, classes, variables, ...) in [camel case](https://en.wikipedia.org/wiki/Camel_case) (capital first letter for classes) and avoid abbreviations when possible.
 
 ## Testing
 We use [Jest](https://jestjs.io/) as our testing framework. All unit tests can be found inside the `test/` folder that reflects the structure of the `src/` folder.

docs/CONTRIBUTING.md

@@ -2,31 +2,44 @@
 If you'd like to contribute to Blackrik, please make sure you follow our [guidelines](#guidelines).
 
 # Guidelines
+To make development easier, there are a few rules that should be respected (yeah I know... rules 😒 but without them it would turn into an anarchy).
+
+Just stick to our [workflow](#Workflow) and you should be fine.
 
 ## Workflow
 Before you start, make sure there is no open issue that proposes your feature or fix (or whatever).  
 If there is already an issue that kinda fits but does not exactly match your proposal, hook into the discussion.
 
 Otherwise
 1. Create a new [issue](https://guides.github.com/features/issues/) so your proposal can be discussed first.
-2. Create a new [branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches) of this repository to work in.
+2. Create a new [branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches) of this repository to work in (see [branches](#Branches) for naming).
 3. Implement your feature or fix or enhancement.
-4. Add (or update) [tests](#testing) if needed.
-5. Make sure your code complies with our [codestyle](#codestyle): `$ npx eslint .`.
+4. Make sure your code complies with our [codestyle](#codestyle): `$ npx eslint .`.
+5. Add (or update) [tests](#testing) if needed.
 6. Make sure all [tests](#testing) pass: `$ npm run test`.
 7. Commit all changes to your branch (from step 2) and write useful commit messages for others to be able to undestand what changed.
 8. Create a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) (PR) to inform others about your changes.
 9. Your PR will be reviewed. If changes are requested, simply commit these to your branch.
 10. After everything's right, someone will merge your branch into the master branch.
 
+## Branches
+When creating a new branch use the pattern `<category>/<topic>` or `<category>/<issue>/<topic>` for its name. Category may be one of the following `feature`, `bugfix`, `hotfix`, `docs`, ...  
+While the topic describes what exactly the branch is about.  
+You may add an issue id in-between e.g. `feature/42/my-feature` if issue #42 belongs to "my-feature".
+
+Try to keep the name short e.g. instead of:  
+`bugfix/there-is-a-bug-where-the-api-explodes-when-calling-specific-routes`  
+just use:  
+`bugfix/api-explosion`
+
 ## Codestyle
-We use [ESLint](https://eslint.org/) to make sure the code has a constant style. That style is described via rules inside the [.eslintrc.js](https://github.com/wesone/blackrik/blob/master/.eslintrc.js) file.
+We use [ESLint](https://eslint.org/) to make sure the code has a consistent style. That style is described via rules inside the [.eslintrc.js](https://github.com/wesone/blackrik/blob/master/.eslintrc.js) file.
 
 To test if all rules are satisfied run `$ npx eslint .` from the project's root directory (or `$ npx eslint <dir>`).  
 ESLint can fix some problems automatically if you use `$ npx eslint --fix .` but be advised that the `--fix` flag might manipulate your code.
 
 ### Naming
-Please use descriptive names (for functions, parameters, classes, variables, ...) in [camel case](https://en.wikipedia.org/wiki/Camel_case) and avoid abbreviations when possible.
+Please use descriptive names (for functions, parameters, classes, variables, ...) in [camel case](https://en.wikipedia.org/wiki/Camel_case) (capital first letter for classes) and avoid abbreviations when possible.
 
 ## Testing
 We use [Jest](https://jestjs.io/) as our testing framework. All unit tests can be found inside the `test/` folder that reflects the structure of the `src/` folder.

docs/Config.md

@@ -99,7 +99,7 @@ sagas: [
 ```
 
 # adapter
-The framework needs a store for it's core stuff (e.g. to persist [scheduled commands](Blackrik#schedulecommand)).  
+The framework needs a store for its core stuff (e.g. to persist [scheduled commands](Blackrik#schedulecommand)).  
 The specified adapter needs to be the name of one of the stores from the [readModelStoreAdapters](#readModelStoreAdapters) object.  
 By default the adapter `'default'` will be used. 
 
@@ -115,7 +115,7 @@ Refer to [read model store adapter](ReadModelStoreAdapter) to see how to create
 
 The property `module` is a string that contains the full path to the adapter (or just the name of the module if the module is a stand-alone package).
 
-The property `args` will be used as a configuration for the adapter and it's content will depend on the adapter.
+The property `args` will be used as a configuration for the adapter and its content will depend on the adapter.
 
 ### Examples
 ```javascript
@@ -141,7 +141,7 @@ Refer to [event store adapter](EventStoreAdapter) to see how to create an event
 
 The property `module` is a string that contains the full path to the adapter (or just the name of the module if the module is a stand-alone package).
 
-The property `args` will be used as a configuration for the adapter and it's content will depend on the adapter.
+The property `args` will be used as a configuration for the adapter and its content will depend on the adapter.
 
 ### Examples
 ```javascript
@@ -162,7 +162,7 @@ Refer to [event bus adapter](EventBusAdapter) to see how to create an event bus
 
 The property `module` is a string that contains the full path to the adapter (or just the name of the module if the module is a stand-alone package).
 
-The property `args` will be used as a configuration for the adapter and it's content will depend on the adapter.
+The property `args` will be used as a configuration for the adapter and its content will depend on the adapter.
 
 ### Examples
 ```javascript

docs/README.md

@@ -16,7 +16,7 @@ There are 3 major parts inside a Blackrik application.
 
 ### [Aggregates](Aggregates)
 An aggregate represents a state of a single unit inside your system (e.g. user).  
-It receives [commands](Aggregates#Commands) that request changes to the unit's state (e.g. update user).  
+It receives [commands](Aggregates#Commands) that request changes to the units state (e.g. update user).  
 A command can emit an event to tell the system that a state change happened (e.g. user was updated).  
 It also has a [projection](Aggregates#Projection) that uses all events that belong to the unit, to build the current state to be used inside the commands.
 

docs/ReadModelStoreAdapter.md

@@ -4,7 +4,7 @@ The read model store adapter is an interface to a persistence level.
 # Reference
 Visibility | Property
 :---: | :---
-public |     async [defineTable](ReadModelStoreAdapter#defineTable)(name: string, scheme: object, ?options: object): boolean<br>Defines a table and it's structure
+public |     async [defineTable](ReadModelStoreAdapter#defineTable)(name: string, scheme: object, ?options: object): boolean<br>Defines a table and its structure
 public |     async [dropTable](ReadModelStoreAdapter#dropTable)(name: string)<br>Deletes the specified table
 public |     async [find](ReadModelStoreAdapter#find)(name: string, ?conditions: object, ?queryOptions: object): array<br>Loads entries from the store
 public |     async [findOne](ReadModelStoreAdapter#findOne)(name: string, ?conditions: object, ?queryOptions: object): object \| null<br>Loads a single entry from the store
@@ -15,7 +15,7 @@ public |     async [delete](ReadModelStoreAdapter#delete)(name: string, conditio
 
 # defineTable
 `async defineTable(name: string, scheme: object, ?options: object): boolean`  
-Defines a table and it's structure. It will remove and recreate existing tables if their scheme changed.
+Defines a table and its structure. It will remove and recreate existing tables if their scheme changed.
 
 ### Parameters
 Name | Type | Attribute | Description

src/core/Blackrik.js

@@ -225,7 +225,7 @@ class Blackrik
     _registerErrorHandlingMiddlewares()
     {
         // http://expressjs.com/en/guide/error-handling.html
-        // Asynchronous route handlers, middleware must call next(err) otherwise its an unhandled error
+        // Asynchronous route handlers, middleware must call next(err) otherwise it's an unhandled error
         // Starting with Express 5 route handlers and middleware that return a Promise will call next(value) automatically when they reject or throw an error
 
         //TODO use this when Express 5 is production ready