Merge branch 'master' of https://github.com/dolanmiu/docx

docs/contribution-guidelines.md

@@ -1,5 +1,30 @@
 # Contribution Guidelines
 
+## Always think about the user
+
+The number one pillar for contribution is to **ALWAYS** think about how the user will use the library. 
+
+Put yourself in their position, and imagine how they would feel about your feature you wrote.
+
+1. Is it easy to use? 
+2. Has it been documented well?
+3. Is it intuative?
+4. Is it consistent with the rest of the API?
+5. Is it fun to use?
+
+## Good Commit Names
+
+Please write good commit messages when making a commit: https://chris.beams.io/posts/git-commit/
+
+**Do not:**
+```
+c // What?
+rtl // Adding acryonyms without explaining anything else is not helpful
+works! // Glad its working, but the message is not helpful
+demo updated // Getting better, but capitalize the first letter
+Unesesary coment removed // Make sure to use correct spelling
+```
+
 ## Writing Code
 
 *   Include documentation reference(s) at the top of each file:
@@ -45,18 +70,98 @@ public get Level() {
 
 There is no performance advantage by doing this. It means we don't need to prefix all private variables with the ugly `_`:
 
-**Do not:** 
+**Do not:**
 
 ```js
 private get _level: string;
 ```
 
-**Do** 
+**Do**
 
 ```js
 private get level: string;
 ```
 
+## Interfaces over type alias
+
+Do not use `type`, but rather use `Interfaces`. `type` cannot be extended, and a class cannot implement it.
+
+> "In general, use what you want ( type alias / interface ) just be consistent"
+> "always use interface for public API's definition when authoring a library or 3rd party ambient type definitions"
+>
+> *   https://medium.com/@martin_hotell/interface-vs-type-alias-in-typescript-2-7-2a8f1777af4c
+
+`Interface` is generally preferred over `type`: https://stackoverflow.com/questions/37233735/typescript-interfaces-vs-types
+
+**Do not:**
+
+```js
+type RelationshipFileInfo = { id: number, target: string };
+```
+
+**Do:**
+
+```js
+interface IRelationshipFileInfo {
+    id: number;
+    target: string;
+}
+```
+
+## String enums vs type
+
+To take full advantage of TypeScript's typing system, its best to use `string enums`:
+
+**Do not:**
+
+```js
+type WeaponType = "bow" | "sword" | "wand";
+```
+
+**Do:**
+
+```js
+enum WeaponType = {
+    BOW = "bow",
+    SWORD = "sword",
+    WAND = "wand",
+}
+```
+
+## Spell correctly, full and in American English
+
+I am not sure where these habit in software development comes from, but I do not believe it is beneficial:
+
+**Do not:**
+```js
+readdy // misspelling
+perm // abbreviation
+conf // abbreviation
+cnty // abbreviation
+relationFile // abbreviation
+colour // U.K. English
+```
+
+**Do:**
+```js
+ready
+permission
+config
+country
+relationshipFile
+color
+```
+
+## Keep files small (within reason)
+
+To minimize merge conflicts, reduce complexity, and improve readability, keep the files small.
+
+## Name files and folders with `/foo-bar/kebab-case.ts`
+
+To be consistent and in-line with the project, name files `like-this.ts`.
+
+https://stackoverflow.com/questions/7273316/what-is-the-javascript-filename-naming-convention
+
 ## Testing
 
 Please write a test of every file you make and suffix it with `.spec.ts`.
@@ -78,3 +183,5 @@ describe("ClassName", () => {
     });
 });
 ```
+
+Try not to use the `tests/utility.ts` file as this is being deprecated.