Merge pull request #13 from inversify/docs/add-developer-docs

Add developer docs

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing to Inversify monorepo
+
+## Guidelines
+
+- Please follow [unit testing guidelines](./docs/testing/unit-testing.md) when testing your modules.
+
+- Please wite [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Conventional commits are enforced via git hooks and gh actions thanks to [commitlint](https://commitlint.js.org/). The `commit` npm script might be helpful for newcomers.
+
+- Create an issue before sending a PR.
+
+- Feel free to ask for help from other members of the InversifyJS team via the chat / mailing list or github issues.

README.md

@@ -0,0 +1,9 @@
+[![Build status](https://github.com/inversify/monorepo/workflows/build/badge.svg)](https://github.com/inversify/monorepo/workflows/build/badge.svg)
+
+# InversifyJS monorepo
+
+A monorepo for maintaining InversifyJs packages.
+
+## Documentation
+
+- [Developer guides](./docs/introduction.md)

docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+Welcome to the developer docs.
+
+- [Testing docs](./testing/index.md).
+- [Setup docs](./setup.md).

docs/setup.md

@@ -0,0 +1,38 @@
+# Setup
+
+Welcome aboard! In this doc you will be provided with all the relevant knowledge to set up the monorepo packages.
+
+## Requirements
+
+A few software tools are required to set the backend services:
+
+- NodeJS 20. (we strongly suggest using [nvm](https://github.com/nvm-sh/nvm)).
+- [pnpm](https://pnpm.io/) is used as package manager, so be sure you have it globally installed.
+
+## Steps to set up the backend monorepo
+
+1. Clone this repo
+
+```
+git clone https://github.com/inversify/monorepo.git inversify-monorepo
+```
+
+2. Go to the root package
+
+```
+cd inversify-monorepo
+```
+
+3. Install dependencies
+
+```
+pnpm i
+```
+
+4. Build project
+
+```
+pnpm run build
+```
+
+Now you're all set. Enjoy coding!

docs/testing/fixtures.md

@@ -0,0 +1,78 @@
+# Fixtures
+
+Sometimes tests demands intances which are compliant with certain requirements. Those requirements are often shared between multiple modules. Those requirements often change. As developers we want fixture providers which can be easilly used in those scenarios.
+
+The current solution is using fixture classes with static methods used as fixture builders.
+
+## Fixture classes
+
+A fixture class provides several methods used to build fixtures matching certain requirements. Consider the class `User`
+
+```ts
+export enum UserRole {
+  commoner,
+  lord,
+}
+
+export interface User {
+  id: string;
+  role: UserRole;
+  username: string;
+}
+
+```
+
+An `User` fixture class could be the following one:
+
+```ts
+import { User } from 'path/to/user';
+import { User } from 'path/to/user/role';
+
+export class UserFixtures {
+  public static get any(): User {
+    const fixture: User = {
+      id: '6a920dea-cce7-4360-ab93-1dfe2b7477a2',
+      role: UserRole.commoner,
+      username: 'John Doe',
+    };
+
+    return fixture;
+  }
+
+  public static get withRoleCommoner(): User {
+    const fixture: User = {
+      ...UserFixtures.any,
+      role: UserRole.commoner,
+    };
+
+    return fixture;
+  }
+
+  public static get withRoleLord(): User {
+    const fixture: User = {
+      ...UserFixtures.any,
+      role: UserRole.lord,
+    };
+
+    return fixture;
+  }
+
+  public static get withUseCaseMeaningfulUseCaseNameEntityAlias(): User {
+    const fixture: User = {
+      // Build your user with the use case requirements
+    };
+
+    return fixture;
+  }
+}
+
+```
+
+The `any` fixture represents any user. It means if you want a user who should be a `commoner`, **do not** use the `any` fixture, use the `withRoleCommoner` one.
+
+Fixture classes methods must follow a nomenclature convention:
+- A fixture class method can be named `any`.
+- A fixture class method can be named `with[propertyValueList]`, where `propertyValueList` is a string describing a sequence of property assignments:
+  - `withRoleCommoner`
+  - `withRoleLordAndUsernameSophie`
+- A fixture class method can be named `withUseCase[meaningfulUseCaseName][entityAlias]`, where `meaningfulUseCaseName` is a use case name such as `PostUserApiV3_001`. Any use case must be documented and maintained, so generating use cases is a worst case scenario to be avoided if possible.

docs/testing/index.md

@@ -0,0 +1,3 @@
+# Testing
+- [Writing fixtures](./fixtures.md).
+- [Writing unit tests](./unit-testing.md).