CONTRIBUTING.md

Contributing

The project is open and any contribution is welcome!

There are many ways to contribute to the XMPP Web such as reporting bugs, suggesting features and submitting pull requests.

Developers guidelines

Discuss first

Before writing code / submitting pull request, please create a feature request in order to discuss your idea.

Code style

When writing some code, lint it with provided rules: pnpm run lint.

Commits message

Read conventional commits and write your commit messages accordingly. You can add provided git commit-msg hook (which execute a basic message checking) with the following command: pnpm run configure-git-hook.

Architecture

Application is build around 4 components:

• XmppClient.js which is responsible for low-level XMPP logic (connect, parse stanza, ...) it relies on xmpp.js,
• XmppSocket.js which is responsible for application level XMPP logic,
• Pinia store which, as its name implies, store the data (contacts, rooms, messages, ...) for the entire application (Vue components read data through it),
• Vue components which include display and interaction logic of their own. These are divided into three folders:
  • src/components/Registered/ for components dedicated to logged-in users,
  • src/components/Guest/ for components dedicated to anonymous users,
  • src/components/Shared/ for components used on the two types of access above.

Tests

Before packaging, the application's functionality is validated by a set of Cypress tests. It is strongly recommended that you include tests for your new features or update existing tests affected by your changes.

Edit frontend code (VueJS)

This app is build using Vue 3, you can found useful information on documentation.

The UI part is using Oruga library.

1. Fork and clone repo

In order to contribute to this application, you need to:

1. Fork the repo and clone it in folder of your choice (in example /var/www/xmpp-web): git clone https://github.com/<your_user>/xmpp-web.git /var/www/xmpp-web
2. Access the frontend folder in a shell cd /var/www/xmpp-web for next steps (2a or 2b, then 3)

2-a. Dev tools by installing prerequisite...

1. install prerequisite:

• Node.js
• npm npm install npm@latest -g
• pnpm npm install -g pnpm@latest-10

2. Build the project pnpm install and wait for the downloads
3. Start the vite server pnpm run dev

2.b. ...or dev tools by using Dockerfile-dev

If you are using Docker, you can use the Dockerfile-dev to avoid installing Node.js on your local computer:

1. Build dev image:

   docker build \
   -f docs/docker/Dockerfile-dev \
   -t nioc/xmpp-web:node-alpine-dev \
   .
   

2. Run run vite server in container:

   docker run -it \
   -p 3000:3000 \
   --rm \
   -v "$(pwd)":/app \
   -v "/app/node_modules" \
   --name xmpp-web-1 \
   nioc/xmpp-web:node-alpine-dev
   

3. Do your work

1. Open your browser on http://localhost:3000 (vite handle hot reload after changes)
2. Edit public/local.js according to your XMPP server configuration (you can add it in .gitignore file to avoid to restore it before commit)
3. Edit the code (I suggest using Visual Studio Code with Vetur)
4. When you are satisfied with your work, run the linter pnpm run lint
5. Create a dedicated branch with explicit feature name git checkout -b feat#123-my_awesome_feature
6. Commit your changes (with a detailled message, using conventional commits): git commit -am 'feat(guest): Add an awesome feature for guest' -m 'Close #123'
7. Push to the branch: git push origin feat#123-my_awesome_feature
8. Submit a pull request

XMPP server backend

You can find some docker XMPP server setups in this folder.