Skip to content

Latest commit

 

History

History
167 lines (127 loc) · 8.05 KB

CONTRIBUTING.md

File metadata and controls

167 lines (127 loc) · 8.05 KB
Raw

Contributor Guidelines

🌟 Thank you 🌟 for contributing to the TooLiP app!

Overview

TooLiP is an online suite of tools that helps language researchers work with their data.

General Guidelines

  • Each tool is a standalone page within the website focused on helping linguists perform a single task. More complex tools should be integrated into the data management app (Lotus) or the data explorer portal (Oxalis).
  • Tools should use formats and libraries from the Digital Linguistics (DLx) project.
  • The site is designed to work offline. Tools should function without need for a server connection or calls to an external API (though this can happen optionally).

Getting Started

  1. Install the latest LTS version of Node.

  2. Clone this repository and navigate into its folder.

    > git clone https://github.com/digitallinguistics/tools.git
> cd tools

    If you're unfamiliar with the command line, consider installing GitHub Desktop instead in order to sync your code with GitHub.

  3. Install the software dependencies for the project.

    > npm install

  4. Build the app and start a local server. This will start 11ty, and rebuild the app automatically when your code changes.

    > npm start

  5. View your development version of the site at http://localhost:3000.

  6. End-to-end tests are run using Cypress. You can run them programmatically by running npm test on the command line in the project root, or you can first start the server, and then (in a new command terminal) open the Cypress interface to run them manually using npm run open-cypress.

Project Structure

  • .github: GitHub configuration files
  • build: build scripts
  • dist/: the compiled website (not checked into git)
  • src: the source code for the site (this is the folder processed by 11ty)
  • src/assets: static assets such as fonts, images, etc.
  • src/classes: global CSS classes used across the site
  • src/components: global components (combination of an HTML partial + accompanying CSS) used across the site
  • src/layouts/main: the main layout which serves as the app shell
  • src/layouts/main/components: components that are only used in the app shell
  • src/layouts/main/styles: global styles that are loaded as part of the app shell (CSS reset, typography, etc.)
  • src/tools/{tool}: source code for individual tools
  • utilities: JavaScript utilities
  • eslint.config.js: contains all the settings for building the site

Tools Structure

  • {tool-name}.html: The HTML for the tool. (More below.)
  • {tool-name}.css: This will be bundled and inlined automatically during build. Import all CSS dependencies for the tool into this file.
  • {tool-name}.js: This will be bundled and inlined automatically during build. Import all JS dependencies for the tool into this file.
  • {tool-name}.test.js: The E2E tests to run for this tool.
  • css/: Use this subfolder for tool-specific CSS dependencies.
  • js/: Use this subfolder for tool-specific JS dependencies.

Tools To-Dos

A checklist to work through for each tool.

  • Add a purpose/overview to the Home page.
  • If helpful, add a README.md to the folder for that tool.
  • Add dismissable/hidable directions / help text to the page.
  • Add a note about which libraries are being used in the tool, with links, at the bottom of the page.
  • Allow the user to save their work + settings to local storage.
  • Set up domain redirects: transliterate.digitallinguistics.io > tools.digitallinguistics.io/transliterate
  • Allow data portability (import/export).
    • copy-paste
    • file upload/download
    • cloud services
  • Update issue templates to include the tool as an option.

HTML

  • Copy the Template page in src/tools/template/template.html when starting a new tool.
  • Each tool's HTML should be wrapped in <main class={tool-name} id=main>.
  • Each tool page needs to start with a YAML header with the following attributes:
Property Format Description
permalink /{tool-name}/ The path where the tool will live. Must include the trailing slash.
title {Tool Name} This will appear in the browswer tab as "TooLiP | {Tool Name}"

Resources

  • Feather Icons: DLx projects use Feather Icons for UI by default, or similar styles when Feather does not have a specific icon available.

Dependencies

  • 11ty: The static site generator used to build the site. Mostly useful for its layout functionality.
  • Cypress: For E2E testing.
  • esbuild: For bundling JS and CSS.
  • ESLint: For linting JavaScript. Uses an opinionated set of style rules.
  • flexbox-reset: A CSS reset that uses flexbox by default for many elements that are typically rendered as block elements.
  • Stylelint: For linting CSS. Uses an opinionated set of style rules.
  • svgstore: Creates SVG sprites.

NOTE: This project does not use either a JavaScript transpiler or a CSS preprocessor. You should only use features that are supported by the current versions of the major evergreen browsers (Chrome, Edge, Firefox, Safari).

DLx Dependencies

  • design: Design components shared across DLx projects.
  • eslint-config: An opinionated JS code style set shared across DLx projects.
  • stylelint-config An opinionated CSS code style set shared across DLx projects.
  • styles: CSS styles for presenting linguistic data and documents on the web.

Individual tools also use various DLx dependencies. You can explore all the DLx projects here.

Versioning & Releases

While in initial development (v0.1.0), the site deploys to GitHub Pages every time a change is pushed to main.

Later, only releases will be deployed, and this will be accompanied by a change in version number.

Increment version numbers based on the following events.

  • major:
    • site overhaul
    • major overhaul to a tool
    • new tool added
    • tool removed
  • minor:
    • new functionality added
    • changes to an existing tool
  • patch:
    • bug fixes
    • changes to development environment
    • changes to documentation