Skip to content

Latest commit

 

History

History
173 lines (121 loc) · 6.05 KB

CONTRIBUTING.md

File metadata and controls

173 lines (121 loc) · 6.05 KB
Raw

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.

⚠️ 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

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.

Team organization

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 Theme tag.
  • 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 Epic tag.
  • The common tasks are issues on GitLab and these issues depend on an epic or are a bug/feature.

Springs/Milestones

Please, for further information about the Springs, go to the RELEASE_NOTES.md doc.

Pending tasks

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:

How to MR

In order to submit a PR, please follow the next steps:

  1. Fork the target repository of BabiaXR on GitLab.
  2. Do the development/action.
  3. 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:

  1. Clone the repository:

    git clone https://gitlab.com/babiaxr/aframe-babia-components

  2. Install the dependencies:

    cd aframe-babia-components
npm install

  3. Deploy the dev server:

    • Without SSL: 
      npm run dev
      or 
      npm start
    • With SSL: 
      npm run ssldev
    • With SSL, access from all hosts 
      npm run ssldevall

Each change in a file will automatically update the dev server.

Warning notice: 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.js and aframe-babia-components.min.js inside the dist/ folder.

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 require sintax:

// 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 tests folder.

When a test file includes to create snapshot or videos, will save it into /screenshots and /videos folders.

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 (firefox or chrome):

npm run test:firefox

or

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.