CONTRIBUTING.md

Contributing Guidelines

Thank you for being interested in contributing to Basement Chat! Here's the guide we want you to follow:

• Development Setup
• Coding Rules
• Commit Message Guidelines
• Submitting a Pull Request (PR)

Development Setup

Requirements

To start developing Basement Chat, make sure you have installed

• node >= 18
• php >= 8.1
• docker or chromium to run Laravel Dusk browser tests.

Installation

• Create a new folder for your project directory. For example, we will call it basement-chat.

  └── basement-chat
  

• Clone this repository and package development branch demo repository in your basement-chat project directory:

  git clone -b package-development https://github.com/basement-chat/demo.git
  git clone https://github.com/basement-chat/basement-chat.git
  

• Now, the directory structure will be something like this:

  └── basement-chat
      └── basement-chat
      └── demo
  

• Inside the basement-chat/demo folder:

  • Add the following configuration to your composer.json, this will allow you to install the local basement-chat/basement-chat project as a dependency:

    "repositories": [
        {
            "type": "path",
            "url": "../basement-chat"
        }
    ]

  • You need to run the following command to install basement-chat/basement-chat from local directory and install npm dependencies:

    composer require basement-chat/basement-chat:dev-main
    npm install
    

  • Copy from .env.example to .env and configure your environment as usual. Here, we will use the default configuration and create a new empty file to database/database.sqlite.

    touch database/database.sqlite
    

  • Run the database migration with the following command:

    php artisan migrate
    

  • Seed your database with pre-filed users and messages:

    php artisan db:seed
    

  • Build assets with:

    npm run build
    

  • Run the soketi server:

    npx soketi start
    

  • Run the PHP server:

    php artisan serve
    

• Inside the basement-chat/basement-chat folder:

  • Run the following command to install all required dependencies:

    composer install
    npm install
    

  • Run the Vite development server and copy the hot file to the basement-chat/demo/public folder:

    npm run dev
    cp ./public/hot ../demo/public/hot
    

  • When you modify the code in this basement-chat/basement-chat folder, all changes will be reflected to http://127.0.0.1:8000

Running tests

When modifying source code files, you can use the following commands to check if your changes break the test:

• Run unit tests:

  composer run-script test:unit
  

• Run feature tests:

  npx soketi start
  composer run-script test:feature
  

• Run browser tests:

  ./vendor/orchestra/testbench-core/create-sqlite-db
  ./vendor/orchestra/testbench-dusk/create-sqlite-db
  ./vendor/bin/dusk-updater detect --auto-update
  npx soketi start
  composer run-script test:browser
  

  Since the browser test is a bit tricky as it may fail depending on your OS environment, it is generally recommended to run tests with docker using the following command:

  docker-compose --file .devcontainer/docker-compose.yml run --rm test
  

  All failed browser test results including logs and screenshots will be stored in tests/Browser/console/ and tests/Browser/screenshots/

Debugging Guide

The Basement Chat package is integrated with Laravel Dump Server. This feature makes it easy to perform interactive print debugging. So whenever you use dd or dump, the dumped data can be seen in the given URL (by default it uses http://localhost:8080/):

composer run-script dumper:start # start var dump server
composer run-script dumper:serve # serve dumped data to http://localhost:8080

Commonly used scripts

• Composer
  • composer run-script analyse: run static code analysis using PHPStan
  • composer run-script canvas: run code generators using canvas, similar to the artisan make command
  • composer run-script format: format .php files to PSR-12 code style using Laravel Pint
  • composer run-script insights: run code quality analysis using PHPInsights
  • composer run-script test: run the unit, feature, and browser tests using PHPUnit and Laravel Dusk
• NPM
  • npm run commit: commit changes with Conventional Commits rules using Commitizen
  • npm run build: build production bundles of .ts and .css assets using Rollup
  • npm run dev: run the Vite development server
  • npm run format: format .yml, .css, .blade.php, and .json files using Prettier
  • npm run lint: fix .js and .ts files to Airbnb code style using ESLint

Coding Rules

Here are some guidelines on the code styles used in the Basement Chat project:

PHP

• Code should be written in PSR-12, and the following command can be used to automatically fix your code style using Laravel Pint

  composer run-script format
  

• Adding PHPDoc to the PHP files you write is not necessary but is highly recommended so it will work well with static analysis using PHP Stan. If you are not familiar with PHPDoc and PHPStan, you can try reading the following guide. To run static code analysis, you can use the following command:

  composer run-script analyse
  

  If you're familiar with TypeScript, think of it like JSDoc in JavaScript with // @ts-check inside.

Blade views

• Directory structure should be organized using Atomic Design. Here's a brief explanation if you're not familiar with this methodology:
  • atoms are UI elements that can’t be broken down any further and serve as the elemental building blocks of an interface. Examples: button, icon, and input.
  • molecules are collections of atoms that form relatively simple UI components. Examples: form-group.
  • organisms are relatively complex components that form discrete sections of an interface. Examples: chat box header component, private messages component, and contacts component.

  └── resources
      └── views
          └── components
              ├── atoms
              ├── molecules
              └── organisms
  

  For more details, you can read on the following page.
• Code style should use prettier with our opinionated configuration, this can be automatically fixed using the following command:

  npm run format:blade
  

CSS

TailwindCSS class should be prefixed with bm- to prevent style conflicts.

TypeScript

Basement Chat uses a customized code style based on Airbnb guide. You can fix your code style automatically using the following command:

npm run lint

Commit Message Guidelines

To make sure every commit work well with our Semantic Release CI/CD, it is expected that your commit messages follow the Conventional Commits. Don't get overwhelmed, you just need to run the following command in the terminal when you commit:

npm run commit

And it will automatically run Commitizen to interactively prompt you for commit message type and description.

Submitting a Pull Request (PR)

Consider these guidelines before submitting PR:

• Make sure the PR that you would like to create has not been assigned by someone else. Please see the roadmap page or pull requests page to find out.

• When you have a new idea that hasn't been listed on the roadmap, feel free to open a PR draft or issue first to discuss your idea.

• Don't commit your dist folder when building assets as it will be hard to review your changes. Instead, we build assets using CI/CD when changes are merged into the core branch.

• It is highly recommended that your code follows our coding rules.

• Don't forget to make sure you have tested the changes you made, both manually testing and running automated tests.

• Write clear commit messages according to our guidelines and include relevant information about the changes you've made.