Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
107 lines (71 loc) · 4.79 KB

CONTRIBUTING.md

File metadata and controls

107 lines (71 loc) · 4.79 KB

Contributing

We value and encourage community contributions.

To get started, here's a few important guidelines we would like you to follow:

  1. Code of Conduct
  2. Issues
  3. Vulnerabilities
  4. Development
  5. Pull Requests

1. Code of Conduct

Please read and follow our Code of Conduct.

2. Issues

Engagement always starts with an Issue where conversations and debates can occur around bugs and feature requests:

  • ✅ Do search for a similar / existing Issue prior to submitting a new one.
  • ❌ Do not use issues for any personal support. Use Discussions or StackOverflow instead.
  • ❌ Do not side-track or derail issues threads. Stick to the topic please.
  • ❌ Do not post comments using just "+1", "++" or "👍". Use Reactions instead.

👾 Bugs

A bug is an error, flaw or fault associated with any part of the project:

  • ✅ Do search for a similar / existing Issue prior to submitting a new one.
  • ✅ Do describe the bug concisely, avoid adding extraneous code, logs or screenshots.
  • ✅ Do attach a minimal test or repo (e.g. CodePen, jsFiddle) to demonstrate the bug.

💡 Feature Requests

A feature request is an improvement or new capability associated with any part of the project:

  • ✅ Do search for a similar / existing Issue prior to submitting a new one.
  • ✅ Do provide sufficient motivation / use case(s) for the feature.
  • ❌ Do not submit multiple unrelated requests within one request.

TIP: We suggest that you engage as much as possible within an Issue prior to proceeding with any contributions.

3. Vulnerabilities

A vulnerability is typically a security-related risk associated with any part of the project (or any dependencies):

  • ✅ Do refer to our Security Policy for more info.
  • ✅ Do report vulnerabilities via this link.
  • ❌ Do not report any Issues or mention in public Discussions for discretionary purposes.

4. Development

🌱 Branches

  • develop - Default branch for all Pull Requests.
  • main - Stable branch for all periodic releases.

🔒 Dependencies

  • Git (v2+)
  • Node.js (v16+)
  • NPM (v7+)
  • VS Code + recommended extensions (recommended, but not required).

📦 Project Setup

  1. Fork the repository and create a branch from develop.
  2. Clone the forked repo, checkout your branch, and run npm ci inside the repository root.
  3. Start up the dev server with npm run serve.

📂 Directory Structure

When contributing to the library, please note the following key files and directories:

├── src
│   ├── index.ts
│   ├── Widget.ts
│   ├── ...
  • src - Contains all source file in a flat structure. Contents:
    • index.ts - The library index, containing all library exports.
    • Widget.ts - The main widget class and web component.

🏷 Naming Conventions

  • ✅ Do use lower case kebab-case for module file and folder names, e.g. my-utils.ts. 🍢
  • ✅ Do use uppercase first letter CamelCase for class file names, e.g. MyClass.ts.
  • ✅ Do match a class name with its file name, e.g. MyClass.ts contains export class MyClass { ... }.
  • ✅ Do prefix the custom element name with omni-.
  • ❌ Do not use any verbs or prefixes within property names, instead do use nouns, e.g. mode, position.
  • ✅ Do follow standard TypeScript, Lit related conventions.

🎯 Definition of Done

Here's a non-exhaustive list of requirements that are key to contributing to this project.

5. Pull Requests

  • ✅ Do ensure the branch is up to date with the develop branch.
  • ✅ Do ensure there's no conflicts with the develop branch.
  • ✅ Do ensure that all automatic checks pass. ✔