Skip to content

Latest commit

 

History

History
153 lines (103 loc) · 6.69 KB

CONTRIBUTING.md

File metadata and controls

153 lines (103 loc) · 6.69 KB
Raw

Contributor Guidelines

🌟Thank you🌟 for contributing to the Oxalis app!

Contents

Overview

Oxalis is a multi-page app focused on allowing users to view, search/filter, and aggregate linguistic data of various types (texts, utterances, and lexical items). Because it is a data-intensive app and aims to manage large volumes of scientific data, performance is a key consideration. As such, most data-related operations will take place on the server, and be delivered to the user as (mostly-)static HTML pages.

Project Principles

Develops should keep the following aims and principles in mind when designing and implementing features for Oxalis.

  • community orientation: The data in Oxalis should be accessible to non-specialists like speakers and community members, in addition to research linguists.

  • ethics and data privacy: Developers should be sensitive to the fact that different datasets have different privacy requirements and ethical considerations. Users should be given full flexibility to manage access permissions for their data.

  • linguistic diversity: Oxalis aims to support data from any language in the world, and therefore needs to avoid Indo-European bias. This includes allowing for choice of RTL and LTR writing across the app, choices of font, etc.

  • Principles of Data Citation in Linguistics: A key goal of this project is to make linguistic data accessible, discoverable, and verifiable, all while adhereing to ethical concerns regarding data management in documentary linguistics.

  • Tromsø recommendations for citation of research data in linguistics: Similar to the Austin principles, this project also aims to abet better data citation practices in linguistics.

  • mobile support: Users should be able to easily access data across a variety of devices of different screen sizes and internet speeds. This is especially important for rural communities that may be using the app.

  • open source: Digital Linguistics is committed to open source development.

  • scientific transparency: Data in Oxalis should be easily citable and search results replicable.

Getting Started

  1. Install the latest LTS version of Node. If you need to use multiple versions of Node on the same computer, consider using nvm (Unix, MacOS, and Windows WSL) or nvm-windows.

  2. Clone the repository and cd into its folder:

    > git clone https://github.com/digitallinguistics/data-explorer.git
> cd data-explorer

    If you're unfamiliar with the command line, you may way to install [GitHub Desktop], an easy-to-use interface for syncing your code with git repositories.

  3. Install the software dependencies for the project.

    > npm install

  4. Start a local server.

    > npm start

  5. Visit https://localhost:3001 to view the app.

Technologies & Developer Tools

This app is developed using the Express framework, and Handlebars templates for rendering.

This project uses the following developer tools:

  • Chai: assertion library
  • Cypress: integration testing
  • ESLint: JavaScript linting
  • LESS: CSS preprocessor
  • Mocha: testing framework
  • nodemon: automated restart of application

Naming Conventions

  • Use block__element conventions for naming components, e.g. footer__nav for a nav component inside a footer.

Testing the App

Oxalis has both unit and integration tests. Unit tests are written in Chai + Mocha, and integration tests are written using Cypress.

  • Unit tests are run with npm run unit-tests.
  • Integration tests are run with npm run cypress. This will start a server and open the Cypress test runner.
  • All tests can be run with npm test.

Guidelines

  • Each service should have its own unit test suite.
  • Middleware should be tested by checking its effects on the server response.

Resources

Images

DLx projects use Feather Icons for UI purposes by default. More decorative icons can be found at Flaticon. Generally, UI icons should be black and white with rounded edges, while decorative icons should be colorful and flat with sharp edges.

Versioning

Oxalis loosely follows semantic versioning principles.

  • major: Significant change to UI or existing functionality.
  • minor: Addition of new functionality, such as a new page.
  • patch: Bug fixes and updates to documentation.

Until the MVP milestone is complete, Oxalis uses major version 0 for initial development.

Releases

Currently, Oxalis releases should be tiny and incremental, containing just one or a few changes per release.

Each release should be accompanied by detailed release notes.

Steps to make a release:

  1. Update the Home and About pages as needed.
  2. Update any documentation pages as needed.
    • readme
    • contributing
    • PR templates
    • issue templates
  3. Update project version: npm version {major|minor|patch}
  4. Build the project: npm run build
  5. Prepare the release: npm run prepare-release
  6. Create and merge a PR for the release.
  7. Create a release on main with the new version number.
  8. GitHub Actions deploys the release to the production server.
  9. Test the release on production.