Contributing to BabiaXR
This guide collects information about how to deploy babiaXR locally, how to create a new component and add it to the babiaXR set and how to create the distribution files.
:warning: IMPORTANT : BabiaXR is a set of A-Frame components based on Angle, for further information, please visit the angle main page.
Table of Contents
A high level overview of our contributing guidelines.
- Contributing process to the project
- Deploy a dev server locally
- Build distribution files
- Develop code in BabiaXR
- Testing code in BabiaXR
Contributing process to the project
BabiaXR is an open-source project hosted on GitLab, all the information about the tasks, the repositories with the code and the webpage are there, if you are on GitHub, please visit https://gitlab.com/babiaxr.
The core developers organize the development using springs of two weeks of duration, each spring is defined as a Milestone of GitLab. In each milestone, some tasks will have done, and the organization of the tasks is the following:
- Topics/Subjects of the tasks are defined as issues in GitLab with the
- Epics are big and complex tasks that have smaller and defined subtasks as children, each epic has a topic assigned. Once all the tasks of an epic are resolved, the epic will be resolved as well. Are defined as issues in GitLab with the
- The common tasks are issues on GitLab and these issues depend on an epic or are a bug/feature.
Please, for further information about the Springs, go to the RELEASE_NOTES.md doc.
We follow a Kanban for each, hosted as a board on GitLab, in the “To Do” list there are the tasks that are prepared to do. In order to see the tasks related to the current spring/milestone, please filter by milestonse the kanban/tasks list:
- Kanban: https://gitlab.com/groups/babiaxr/-/boards
- Tasks list: https://gitlab.com/groups/babiaxr/-/issues
How to MR
In order to submit a PR, please follow the next steps:
- Fork the target repository of BabiaXR on GitLab.
- Do the development/action.
- Submit a Merge Request referring the task/issue if the development resolves it.
Deploy a dev server locally
The steps to reproduce and deploy a dev server for developing babiaXR are:
Clone the repository:
git clone https://gitlab.com/babiaxr/aframe-babia-components
Install the dependencies:
cd aframe-babia-components npm install
Deploy the dev server:
- Without SSL:
npm run dev
- With SSL:
npm run ssldev
- With SSL, access from all hosts
npm run ssldevall
- Without SSL:
Each change in a file will automatically update the dev server.
npm run ssldevall will listen connections in 0.0.0.0,
which means “all network devices in this host, including localhost2”.
This implies that the HTTPS server will accept connections from anywhere
in Internet. While this is quite convenient for connecting external
devices (eg, a VR device), it also exposes your directory to anyone
with HTTPS access to the 8080 port in your host. Use at your own risk.
Build distribution files
In order to build a distribution release for babiaXR, just need to execute the next command:
npm run dist
The webpack service of angle will take the
index.js file and will fetch the needed files and collect them into the distribution files.
Therefore, the command will generate two distribution files,
aframe-babia-components.min.js inside the
Develop code in BabiaXR
In order to develop code for babia, e.g. a new component, you have to add it to the
index.js file using
// index.js file ... require('your_file_path') ...
This is neccessary since the distribution files are based on the information of the
index.js file (see Build distribution files section
). Once the file is added, you can now deploy the dev server and
Testing code in BabiaXR
Currently, we use
cypress testing runner.
Before starting the testing, you need to start the server (with SSL):
npm run ssldev
To start testing, execute the next command:
npm run test
This will run all the test that you’d created into
When a test file includes to create snapshot or videos, will save it into
While development, if you want to test some tests, you can run cypress using:
npm run devtest
If you want to test only one browser (
npm run test:firefox
npm run test:chrome
Certificates for npm sun ssldev to work
This repository comes with certificates that are used by webpack to configure the HTTPS server. They are self-signed, which means they need to be accepted in the browser: usually you will get a warning about certificates not being correct, and will be prompted to acept them. These certificates have been built as follows:
openssl genrsa -out babia_key.pem openssl req -new -key babia_key.pem -out csr.pem openssl x509 -req -days 9999 -in csr.pem -signkey babia_key.pem -out babia_cert.pem rm csr.pem
More details in How to create a HTTPS server, in the Node documentation.
We are using those certificates to avoid Webpack generating new certificates with every new run, which means having to accept them in browser with every new run.