Skip to content

Latest commit

 

History

History
151 lines (106 loc) · 6.27 KB

CONTRIBUTING.md

File metadata and controls

151 lines (106 loc) · 6.27 KB

Contributing to Toggl Button

Thanks for your interest in contributing to Toggl Button!

Please take a read through these guidelines to make the process as smooth as possible.

Adding new integrations

For adding a simple integration, the bitrix24 integration is a good option for inspiration.

All integrations have some maintenance cost - any time the UI is changed, Toggl Button might break. Help future maintainers by trying to be sensibly "future-proof" with your CSS selectors, following the code style you observe elsewhere and avoiding neat code tricks that others might not understand.

All integrations should be tested across both Chrome and Firefox.

Please consider the following with your pull request:

  • Include screenshot(s) of the working integration in your pull request.
  • Include a description of how to find the page or screen the button is visible on.
  • Only change or add one integration in each pull request.
  • Your code changes will be linted by eslint when you attempt to commit. Please fix any errors raised.
    • You may run npm run lint path/to/your/file/here.js to lint a file manually. Add -- --fix to the command to automatically fix most issues.
  • When you're done, squash all of your commits into one commit. This keeps the git log compact and clear.

Toggl Button "style guide":

For integrations that show one button on the page:

  • Use the default appearance

.

  • If the button is placed in a tight spot (such as a toolbar), you can use buttonType: minimal.
  • It's OK for the "Start/stop timer" text color to be changed to fit the integration.
  • You can place the button inside a UI component if it makes sense. Example: Trello

For integrations that show many buttons in a list:

  • Always use buttonType: minimal.
  • The buttons must only be shown on hover or in context menus.
  • Buttons must use the grey icon.
  • When a timer is active, the active button must be shown all the time (instead of only on hover).
  • Active buttons must use the red icon.
  • Please investigate performance. List integrations can have a negative effect.

See the Microsoft To-Do integration for reference.

All buttons:

  • Make sure we're not leaking styles or breaking the layout of the UI.
  • The text used as timer description should be tailored to the majority of users. E.g. if ticket ID is an important piece of information, it should be included. If it's not important information (e.g. never actually shown in the UI, only in URLs) it should not be included.

DOM integration

If you want to quickly integrate Toggl Button with your website. You can enable the DOM Integration in the Custom Integrations section for your domain

enable-dom-integration

You will have to add one or more div in your DOM with the class name toggl-root, containing the metadata for the time-entry you want to start, Toggl Button will render a button link as a child of these divs.

The schema for the time-entry metadata is

interface TogglMetadata {
  'class': 'toggl-root'
  'data-description': string
  'data-project-name': string
  'data-project-id'?: number
  'data-tags'?: string // comma separated tag names
  'data-type'?: 'minimal'
  'data-class-name'?: string
}

The actual DOM node would resemble

<div
  class="toggl-root"
  data-description="Description of the time-entry"
  data-project-name="Name of a project that the entry should be assigned to"
  data-project-id="Optionally the id of the project that the entry should be assigned to"
  data-tags="list,of,tags"
  data-type="minimal"
  data-class-name="name-of-the-integration"
></div>

See toggl-button-dom-demo.now.sh for reference.

Making changes to the core extension code

Please consider future maintainers and the "generic" nature of the extension in mind when writing new features. All changes should be tested across both Chrome and Firefox.

There are a lot of moving parts and different settings in the extension, please do your best to account for them and test that you don't introduce any regressions.

Commit Message Guidelines

We use conventional commit messages

This leads to more readable messages and we use the git commit messages to generate the changelog and trigger new releases.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>[optional scope]: <description>

[optional body]

[optional footer]

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

The footer should contain a closing reference to an issue if any.

Samples:

feat: Add some-new integration

fix(trello):Trello integration

- Update selectors

closes #4

fix: Github project integration

Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies (example scopes: webpack, npm)
  • ci: Changes to our CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature/integration
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests