Merge pull request #1292 from IFRCGo/feature/collaboration-guide

Add collaboration guide

.changeset/fifty-ants-crash.md

@@ -0,0 +1,5 @@
+---
+"go-web-app": patch
+---
+
+Add collaboration guide

.github/workflows/chromatic.yml

@@ -86,6 +86,6 @@ jobs:
       - uses: bitovi/[email protected]
         with:
           install_command: yarn install
-          build_command: yarn build-storybook
+          build_command: yarn build:storybook
           path: packages/go-ui-storybook/storybook-static
           checkout: false

COLLABORATING.md

@@ -1,3 +1,16 @@
-### TODO
+# IFRC GO Collaborator Guide
 
-- [ ] Add collaboration guide
+This document offers guidelines for collaborators on codebase maintenance, testing, building and deployment, and issue management.
+
+## Repository
+- [Issues and Pull Requests](./collaborating/issues-and-pull-requests.md)
+- [Structure](./collaborating/repository-structure.md)
+- [Linting](./collaborating/linting.md)
+- [Technology Used](./collaborating/technology.md)
+
+## Development
+- [Developing](./collaborating/developing.md)
+- [Translation](./collaborating/translation.md)
+- [Building](./collaborating/building.md)
+- [Testing](./collaborating/testing.md)
+- [Release](./collaborating/release.md)

CONTRIBUTING.md

@@ -111,52 +111,63 @@ To begin, ensure you have network access. Then, you'll need the following
 ### Local development
 
 1. Clone the repository using HTTPS, SSH, or Github CLI
-```bash
-git clone https://github.com/IFRCGo/go-web-app.git #HTTPS
-git clone [email protected]:IFRCGo/go-web-app.git #SSH
-gh repo clone IFRCGo/go-web-app #Github CLI
-```
+  ```bash
+  git clone https://github.com/IFRCGo/go-web-app.git #HTTPS
+  git clone [email protected]:IFRCGo/go-web-app.git #SSH
+  gh repo clone IFRCGo/go-web-app #Github CLI
+  ```
 2. Install the dependencies
-```bash
-yarn install
-```
+  ```bash
+  yarn install
+  ```
 3. Copy `app/.env.example` to `app/.env` and update the variables
-```bash
-cp app/.env.example app/.env
-```
+  ```bash
+  cp app/.env.example app/.env
+  ```
 4. Start the development server
-```bash
-yarn start:app
-```
+  ```bash
+  yarn start:app
+  ```
 > [!NOTE]\
 > To work on a specific development task, ensure you have the backend setup appropriately and configured properly.
 5. Create a new branch for your work.
-```bash
-git checkout -b name-of-your-branch
-```
+  ```bash
+  git checkout -b name-of-your-branch
+  ```
 > [!IMPORTANT]\
 >  Ensure there are no lint errors before pushing the changes. Ensure the commit message is clear and concise, summarizing the changes made in the commit. Avoid vague and generic messages. Instead, provide specific details that describe the purpose or impact of the changes.
-6. Once you're happy with your changes, add and commit them to your branch, then push the branch to origin.
-```bash
-git add .
-git commit -m "some message"
-git push -u origin name-of-your-branch
-```
-> [!NOTE]\
+6. Once you're happy with your changes, add and commit them to your branch.If your workflow requires changesets (e.g., when changes will impact versioning or are part of a release), create one before committing. Then push the branch to origin.
+  ```bash
+  # Stage all changes
+  git add .
+  # Create a changeset (if changes will affect versioning, like new features or bug fixes)
+  yarn changeset
+
+  # Commit your changes with a message
+  git commit -m "some message"
+
+  # Push your branch to origin
+  git push -u origin name-of-your-branch
+  ```
+
+>[!NOTE]\
+>Review the [Changesets documentation](./collaborating/release.md#changesets) and the [versioning guidelines](./collaborating/release.md#versioning-guidelines-for-ifrc-go-project) for more details on versioning and tracking changes.
+
+> [!IMPORTANT]\
 > Before committing and opening a Pull Request, please ensure there are no lint errors. Also please create a pull request only when the feature is ready to be merged.
 
 7. Create a Pull Request.
 
 ### Build for Production
 
 1. To build the application for production
-```bash
-yarn build
-```
+  ```bash
+  yarn build
+  ```
 2. To locally preview the production build
-```bash
-yarn preview
-```
+  ```bash
+  yarn preview
+  ```
 
 ### CLI Commands
 

README.md

@@ -17,7 +17,7 @@
 
 ## Getting started
 
-Below are the steps to guide you through preparing your local environment for the IFRC GO Web application development. The repository is set up as a [monorepo](https://monorepo.tools/). The app directory houses the application code, while the packages directory contains related packages, including the [IFRC GO UI](https://www.npmjs.com/package/@ifrc-go/ui) components library. Please review the [Contribution Guidelines](./CONTRIBUTING.md) and [Collaboration Guidelines](./COLLABORATING.md) to gain a deeper understanding of the repository's structure.
+Below are the steps to guide you through preparing your local environment for the IFRC GO Web application development. The repository is set up as a [monorepo](https://monorepo.tools/). The app directory houses the application code, while the packages directory contains related packages, including the [IFRC GO UI](https://www.npmjs.com/package/@ifrc-go/ui) components library. Please review the [Contribution Guidelines](./CONTRIBUTING.md) and [Collaboration Guidelines](./COLLABORATING.md) to gain a deeper understanding of the repository's structure and ensure a smooth experience while contributing to the project.
 
 ### Prerequisites
 

collaborating/building.md

@@ -0,0 +1,20 @@
+### Building
+
+> [!NOTE]\
+> Ensure all the packages have been installed before building the project.
+To build different components of the IFRC GO project, use the following commands.
+
+**IFRC GO Web Application**
+  ```bash
+  yarn build
+  ```
+
+**IFRC GO UI Library**
+  ```bash
+  yarn build:ui
+  ```
+
+**UI Library Storybook**
+  ```bash
+  yarn build:storybook
+  ```

collaborating/developing.md

@@ -0,0 +1,99 @@
+## Development
+
+The stable branch for the IFRC GO application is `develop`. All PRs intended for deployment should be merged into the `develop` branch.
+
+For long-running features, create PRs targeting the specific `project/project-x` branch when working on features related to that project.
+
+### Prerequisites
+
+To begin, ensure you have network access. Then, you'll need the following
+1. [Git](https://git-scm.com/)
+2. [Node.JS](https://nodejs.org/en/) version >=18 / 20+
+3. [Yarn 1](https://classic.yarnpkg.com/en/)
+4. Alternatively, you can use [Docker](https://www.docker.com/) to build the application.
+
+### Local development
+
+1. Clone the repository using HTTPS, SSH, or Github CLI
+  ```bash
+  git clone https://github.com/IFRCGo/go-web-app.git #HTTPS
+  git clone [email protected]:IFRCGo/go-web-app.git #SSH
+  gh repo clone IFRCGo/go-web-app #Github CLI
+  ```
+2. Install the dependencies
+  ```bash
+  yarn install
+  ```
+3. Copy `app/.env.example` to `app/.env` and update the variables
+  ```bash
+  cp app/.env.example app/.env
+  ```
+4. Start the development server
+  ```bash
+  yarn start:app
+  ```
+> [!NOTE]\
+> To work on a specific development task, ensure you have the backend setup appropriately and configured properly.
+5. Create a new branch for your work.
+  ```bash
+  git checkout -b name-of-your-branch
+  ```
+> [!IMPORTANT]\
+>  Ensure there are no lint errors before pushing the changes. Ensure the commit message is clear and concise, summarizing the changes made in the commit. Avoid vague and generic messages. Instead, provide specific details that describe the purpose or impact of the changes.
+6. Once you're happy with your changes, add and commit them to your branch.If your workflow requires changesets (e.g., when changes will impact versioning or are part of a release), create one before committing. Then push the branch to origin.
+  ```bash
+  # Stage all changes
+  git add .
+  # Create a changeset (if changes will affect versioning, like new features or bug fixes)
+  yarn changeset
+
+  # Commit your changes with a message
+  git commit -m "some message"
+
+  # Push your branch to origin
+  git push -u origin name-of-your-branch
+  ```
+
+>[!NOTE]\
+>Review the [Changesets documentation](./release.md#changesets) and the [versioning guidelines](./release.md#versioning-guidelines-for-ifrc-go-project) for more details on versioning and tracking changes.
+
+> [!IMPORTANT]\
+> Before committing and opening a Pull Request, please ensure there are no lint errors. Also please create a pull request only when the feature is ready to be merged.
+
+7. Create a Pull Request.
+Please read the [Issues and Pull Requests](./issues-and-pull-requests.md) guide for further information.
+
+### CLI Commands
+
+This repository contains several scripts and commands for performing tasks. The most relevant ones are described below.
+
+<details>
+  <summary>Commands for Running & Building the Web Application</summary>
+
+- `yarn start:app` runs the Local Development Server, listening by default on `http://localhost:3000/`.
+- `yarn build` builds the Application in Production mode. The output is by default within the `build` folder.
+  - This is used for Deployments (Preview & Production).
+- `yarn preview` previews the production build of the Application.
+- `yarn generate:type` generates the Typescript types for the API using `openapi-typescript`. The output is by default within the `generated` folder within the `app` workspace.
+- `yarn storybook` starts Storybook's local server for the `@ifrc-go/ui` components library, listening by default on `http://localhost:6006/`.
+- `yarn build:storybook` builds Storybook as a static web application for publishing.
+- `yarn build:ui` builds the `@ifrc-go/ui` components library. To reflect any new changes in the components library we must ensure that it is built beforehand.
+</details>
+
+<details>
+  <summary>Commands for Maintenance Tasks</summary>
+Execute the following commands within the `app` workspace.
+
+- `yarn lint` runs the linter for all the css, js, ts, and translation files.
+  - `yarn lint:fix` attempts to fix any linting errors for css, js and ts files.
+- `yarn translatte:generate` generates translation migration file.
+- `yarn surge:deploy` builds and deploys the web application to [surge](https://surge.sh/).
+</details>
+
+
+### UI components library
+Please read the [README](../packages/ui/README.md) and [CONTRIBUTING](../packages/ui/CONTRIBUTING.md) guide for IFRC GO UI.
+
+### Storybook
+Please read the [README](../packages/go-ui-storybook/README.md) and [CONTRIBUTING](../packages/go-ui-storybook/CONTRIBUTING.md) guide.
+

collaborating/issues-and-pull-requests.md

@@ -0,0 +1,50 @@
+## Issues
+Use the repository's [Issues](https://github.com/IFRCGo/go-web-app/issues) tab to report bugs, suggest features, and track tasks. Provide clear and detailed descriptions, including steps to reproduce bugs if applicable.
+
+## Pull Requests
+Before you submit your Pull Request (PR) consider the following guidelines.
+
+Please make your changes in a new Git branch following our branch naming conventions. We should use prefixes in branch names:
+- **Project branches**: Prefixed with `project/`, these branches are for long-running features.
+- **Feature branches**: Prefixed with `feature/`, these branches are used to develop new features.
+- **Bugfix branches**: Prefixed with `fix/`, these branches are used to make fixes.
+- **Release branches**: Prefixed with `release/`, these branches prepare the codebase for new releases.
+- **Hotfix branches**: Prefixed with `hotfix/`, these branches address urgent issues in production.
+
+> [!IMPORTANT]\
+>  The name of the branch should be descriptive, concise and consistent. We should use lowercase letters and dashes instead of spaces in branch names to ensure compatibility across different operating systems and Git hosting platforms.
+
+```bash
+git checkout -b feature/new-feature-a develop
+```
+
+Add your changes, ensuring they follow code style guidelines. Run linting, perform type checking, and ensure the build passes.
+
+Run `yarn changeset` in the root of the repository and describe your changes. The resulting files should be committed as they will be used during release.
+
+>[!NOTE]\
+>Review the [Changesets documentation](./release.md#changesets) and the [versioning guidelines](./release.md#versioning-guidelines-for-ifrc-go-project) for more details.
+
+Commit your changes with a clear and descriptive message that adheres to our commit message conventions.
+
+Push your branch to GitHub following our branch naming conventions.
+```bash
+git push origin feature/new-feature-a
+```
+
+On GitHub, open a pull request targeting the `develop` branch or, for changes related to a long-running project, the specific `project/project-a` branch.
+
+If we suggest changes, then make the required updates.
+
+Rebase your branch and force push with `force-with-lease`.
+
+If the target branch is `develop`
+```bash
+git rebase develop
+git push --force-with-lease
+```
+If the target branch is a `project` branch
+```bash
+git rebase project/project-a
+git push --force-with-lease
+```

collaborating/linting.md

@@ -0,0 +1,61 @@
+## Linting and Type Checking
+
+IFRC GO Web App repository utilizes [ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/) for linting and formatting the code, as well as TypeScript for type checking.
+
+> [!NOTE]\
+> Run the following commands withing the [app](../app/) folder
+
+### ESLint
+Configuration for ESLint can be found in the [eslint.config.js](../app/eslint.config.js) file.
+
+To lint your code
+```bash
+yarn lint:js
+```
+
+To automatically fix fixable errors
+```bash
+yarn lint:js --fix
+```
+
+### Stylelint
+
+Configuration for Stylelint is located in the [stylelint.config.cjs](../app/stylelint.config.cjs) file.
+
+To lint your CSS files
+```bash
+yarn lint:css
+```
+
+To automatically fix fixable errors
+```bash
+yarn lint:css --fix
+```
+
+### Fixing Lint Errors
+
+To fix auto-fixable errors in both ESLint and Stylelint
+```bash
+yarn lint:fix
+```
+
+### Type Checking
+> [!IMPORTANT]\
+> Before running the type check, make sure to generate the types.
+> To do this, define the API endpoints in the environment variables first.
+
+To generate the TypeScript types for API endpoints
+```bash
+yarn generate:type
+```
+To verify and enforce TypeScript type constraints
+```bash
+yarn typecheck
+```
+
+### Linting Translation Files
+
+To check for errors in translation files
+```bash
+yarn lint:translation
+```