Frontend sandbox

Using Jason library and Medea WebRTC media server create an application for audio/video calls between two users.

This is a GitHub template repository, so you need to click on Use this template button above and do all the development in your own repository which uses this one as template only.

Required features

Display video and play audio of a partner participant.
Publish video from the frontal camera of a device.
Publishing user's audio.
Preview of the published video.
Ability to enable/disabled published video/audio.

Implementation requirements

Code should be documented with TypeDoc and is able to generate documentation in a form of static website (you may deploy it on GitHub Pages as well).
Code should be covered with unit tests.
E2E (end-to-end) tests should cover all the required features.

WebRTC signaling server

For signaling between client you should use Medea media server with a Jason library.

Read Control API RFC and Client API RFC for better understanding of how it works. You don't need to use Control API directly, instead you may use the following static spec:

kind: Room
id: call
spec:
  pipeline:
    Alice:
      kind: Member
      credentials:
        plain: helloworld
      spec:
        pipeline:
          publish:
            kind: WebRtcPublishEndpoint
            spec:
              p2p: Always
          play-responder:
            kind: WebRtcPlayEndpoint
            spec:
              src: "local://call/Bob/publish"
    Bob:
      kind: Member
      credentials:
        plain: helloworld
      spec:
        pipeline:
          publish:
            kind: WebRtcPublishEndpoint
            spec:
              p2p: Always
          play-caller:
            kind: WebRtcPlayEndpoint
            spec:
              src: "local://call/Alice/publish"

This spec is created automatically for your Medea instance deployed on Heroku.

Deploying on Heroku

Create account on Heroku (if you don't have one).
Copy Heroku API key from the account page.
Go to Actions Secrets settings in your GitHub repository.
Add the following repository keys:
- HEROKU_API_KEY - API key which you copied at step 2;
- HEROKU_EMAIL - email with which you registered on Heroku.
Go to 'Deploy Medea media server to Heroku' GitHub workflow.
Run workflow on master branch.

Now your instance of a Medea media server can be accessed at wss://frontend-sandbox-{{ YOUR GITHUB USERNAME }}.herokuapp.com/ws.

Useful links

Enable GitHub Pages in your repository

Go to Pages settings in your repository
Set GitHub Pages source branch to gh-pages

Now your application will be built and published to the GitHub Pages automatically on every push to master branch.

Final demonstration

Firstly, you should demonstrate that application can make calls between users and disabling/enabling audio/video works correctly.

At the end, your application (published to GitHub Pages) should be able to make video call with a reviewer.

Required assets

All the assets required for this application are located in the assets/ directory.

Final design of application

Final design of the implemented application may vary from the provided one. The provided design aims only to explain the expected result better.

Useful links

Repository requirements

Files

Repository must NOT contain (so have them Git-ignored to avoid accidents):

configuration files of developer's local toolchain (unless this configuration is suitable for all project developers);
compilation/build results/artifacts of source code;
any caches or temporary files;
configuration files for running application (except examples or Dockerized development environment configurations which are the same for all project developers).

For keeping an empty directory in a repository use the .gitkeep file inside that directory.

Naming

Start directory with . if it contains some temporary files which do not require direct manipulations and are going to be omitted by tools (caches, temp files, etc.). This is a quite common practice (see .git/, .idea/, .gradle/, etc.).
Also, all temporary cache files must be placed inside a .cache/ top-level directory of the repository, unless this is impossible for somewhat reasons.

To emphasize toolchain directories (ones which do not contain project sources itself, but rather contain files of a project toolchain) their name may be started with _, which will make them to "bubble-up" in a repository source tree, so will allow easily to distinguish them from actual project sources (both for humans and tools).

Branches and tags

Every repository contains the following branches:

master - mainline version of the project. Any new project release is usually created from this branch. Developing directly in this branch is forbidden. It accepts new changes via PRs (pull requests).

Any other possible branches and tags can be created and used by developers as they need.

Branch naming

Git branch name must meet the following requirements:

consist of English words;
👍 fix-tests-failure
🚫 fix-defectum-probat
use only dashes to separate words;
👍 fix-tests-failure
🚫 fix_tests_failure
use imperative mood for verbs;
👍 fix-tests-failure
🚫 fixes-tests-failure
start with the issue number when branch is related to some issue (but DO NOT use PR (pull request) numbers);
👍 23-fix-tests-failure
🚫 fix-tests-failure
reflect the meaning of branch changes, not the initial problem.
👍 23-fix-tests-failure
🚫 23-problem-with-failing-tests

Commits

Every commit message must contain a short description of its changes that meet the following requirements:

be on English (no other language is allowed);
start with a capital letter;
has no punctuation symbols at the end (like ;, : or .);
use imperative mood for verbs (as if you are commanding someone: Fix, Add, Change instead of Fixes, Added, Changing);
use marked list for multiple changes, prepended by one summary line and one blank line, where each list item must:
- start with a lowercase letter;
- has no punctuation symbols at the end.

👍 Single-line commit message example

Update Employee salary algorithm

👍 Multiple-line commit message example

Implement employees salary and ajax queries

- update Employee salary algorithm
- remove unused files from public/images/ dir
- implement ajax queries for /settings page

🚫 Wrong commit message examples

Summary line starts with a lowercase letter:
```
update Employee salary algorithm
```
Verb is not in the imperative mood:
```
Updates Employee salary algorithm
```

Unnecessary punctuation is present:

Update Employee salary algorithm.

Implement employees salary and ajax queries:

- update Employee salary algorithm;
- remove unused files from public/images/ dir.

Missing blank line between the summary line and the marked list:

Implement employees salary and ajax queries
- update Employee salary algorithm
- remove unused files from public/images/ dir

Marked list is indented:

Implement employees salary and ajax queries

  - update Employee salary algorithm
  - remove unused files from public/images/ dir

Marked list items start with a capital letter:

Implement employees salary and ajax queries

- Update Employee salary algorithm
- Remove unused files from public/images/ dir

FCM (final commit message)

FCM (final commit message) is a commit message of a pull request to a master branch.

As it will be saved in a repository history forever, it has extra requirements that must be met:

contain references to related PR;
do not contain any non-relative helper markers (like [skip ci]);

Common commit messages which are not FCM must NOT contain any references, because references create crosslinks in mentioned PRs, which leads to spamming issues/PRs with unnecessary information. Only saved in history forever commits are allowed to create such crosslinks.

If а PR contains some side changes which are not directly relevant to the task, then such changes must be described as a marked list in the Additionally: section (separated by a blank line) of a FCM.

👍 FCM examples

Implement employees salary and ajax queries (#43, #54)

- update Employee salary algorithm
- remove unused files from public/images/ dir

Additionally:
- update Git ignoring rules for TOML files

🚫 Wrong FCM examples

Bad formatting of [references][103]:

Implement employees salary and ajax queries(#43,#54)

- update Employee salary algorithm
- remove unused files from public/images/ dir

Side changes are not separated:

Implement employees salary and ajax queries (#43, #54)

- update Employee salary algorithm
- remove unused files from public/images/ dir
- update Git ignoring rules for TOML files

Bad formatting of side changes:

Implement employees salary and ajax queries (#43, #54)

- update Employee salary algorithm
- remove unused files from public/images/ dir
Additionally:
- update Git ignoring rules for TOML files

Merging

All merges to the mainline project version (master branch) must have an individual PR (pull request) and must be done only in fast-forward manner. This is required to keep mainline history linear, simple and clear.

To achieve fast-forward merge, all branch commits (which doesn't exist in mainline) must be squashed and rebased onto the latest mainline commit. Notable moments are:

Before rebase do not forget to merge your branch with latest mainline branch updates, otherwise rebase result can break changes.

Squash merging steps

Using GitHub UI

Performing squash merge correctly can be quite tricky when doing manually. To avoid complexity and mistakes in a day-to-day routine the GitHub UI squash merging is the most preferred way for merging and a developer should use it whenever it's possible.

Merge with latest master branch.
Click on Squash and merge button.
Paste first line of FCM to title field.
Paste FCM without first line to body field.
Click Confirm squash and merge.

First line of FCM must go as a title of the squash commit and everything after as a message.

Squash merging via GitHub UI also preserves the whole branch commits history in the PR, which is good for history purposes.

Pushing

Developer must push all his changes to the remote at the end of his working day. This both prevents from accidental work losses and helps a lead to track developer's progress.

Project requirements

All features of application should be added with PRs. Direct push to master is forbidden.

Pull requests

PRs (pull requests) are created to make changes in the repository and to solve some problem (fix a bug, implement a task, provide an improvement, etc).

PR must contain related changes only. Any other unrelated changes of repository must be done via separate PR. This rule keeps project history clear and unambiguous.

PR name must:

shortly and clearly describe its meaning;
contain Draft: prefix until PR is merged or closed.

Not merged or closed PRs should be in draft mode.

PR description must contain details of the solution (background/summary, solution description, notable moments, etc).

Project have PR template which standardize PRs. Developer must use PR template whenever it's possible.
If there is no template for some rare case, then the PR must be formatted in the same manner as available templates.

PR cannot be assigned to nobody and always must have an assigned developer.

PR cannot go without any labels and must have all required labels correctly applied.

Labels

Labels are used for issues/PRs classification, as they:

reflect the current state of issue/PR;
improve understanding of issue/PR, its purpose and application;
provide advanced search of issues/PRs;
allow to sum up statistics of how project is going on.

There are several label groups:

Type labels declare what the current issue/PR actually represents. These labels are mandatory: each issue/PR must have at least one such label.
- feature applies when something new is implemented (or is going to be implemented).
- enhancement applies when changing of existing features is involved (improvement or bugfix).
- rollback applies when some existing changes are going to be rolled back.
k:: labels describe what the current issue/PR is relevant to and which project aspects are involved. These labels are mandatory: each issue/PR must have at least one such label.
- k::ui applies to UI (user interface) and UX (user experience) changes. Use it when end-user are directly affected by this changes.
- k::api applies to API (application interface) changes. Use it when you're changing application interfaces, like: HTTP API method parameters, library exported interfaces, command-line interfaces, etc.
- k::deploy applies to changes that involve application deployment. Use it when you're changing the way application is deployed.
- k::design applies to changes of application architecture and implementation design. Use it when you're changing architecture and algorithms.
- k::documentation applies to changes of project documentation.
- k::logging applies to changes in application logs.
- k::performance applies to application performance related changes.
- k::refactor applies to refactor changes of existing code.
- k::security applies to application security related changes.
- k::testing applies to changes of project tests.
- k::toolchain applies to changes of project toolchain.

Code style

All TypeScript source code must follow TypeScript coding guidelines. For code formatting Prettier must be used (and verified on CI).

`.editorconfig` rules

Project contains .editorconfig file with both general and project-specific code style rules.

Applying .editorconfig rules is mandatory.

Make sure that your IDE supports .editorconfig rules applying. For JetBrains IDE the EditorConfig plugin may be used.

andreyklumchyk/web-chat

Frontend sandbox

Required features

Implementation requirements

WebRTC signaling server

Deploying on Heroku

Useful links

Enable GitHub Pages in your repository

Final demonstration

Required assets

Final design of application

Useful links

Repository requirements

Files

Naming

Branches and tags

Branch naming

Commits

👍 Single-line commit message example

👍 Multiple-line commit message example

🚫 Wrong commit message examples

FCM (final commit message)

👍 FCM examples

🚫 Wrong FCM examples

Merging

Squash merging steps

Using GitHub UI

Pushing

Project requirements

Pull requests

Labels

Code style

.editorconfig rules

`.editorconfig` rules