Skip to content

Latest commit

 

History

History
228 lines (156 loc) · 11.4 KB

CONTRIBUTING.md

File metadata and controls

228 lines (156 loc) · 11.4 KB
Raw

Contributing to Inkline

Actively participate in the development and the future of Inkline by contributing regularly.

Open Source projects are maintained and backed by a wonderful community of users and collaborators.

We encourage you to actively participate in the development and future of Inkline by contributing to the source code, improving documentation, reporting potential bugs or testing new features.

Channels

There are many ways to taking part in the Inkline community.

  1. Github Repositories: Report bugs or create feature requests against the dedicated Inkline repository.
  2. Discord: Join the Discord Server to chat instantly with other developers in the Inkline community.
  3. Twitter: Stay in touch with the progress we make and learn about the awesome things happening around Inkline.

Using the issue tracker

The issue tracker is the preferred channel for bug reports, features requests and submitting pull requests, but please respect the following restrictions:

  • Please do not use the issue tracker for personal support requests.

  • Please do not get off track in issues. Keep the discussion on topic and respect the opinions of others.

  • Please do not post comments consisting solely of "+1" or ":thumbsup:". Use GitHub's "reactions" feature instead. We reserve the right to delete comments which violate this rule.

Issues and labels

Our bug tracker utilizes several labels to help organize and identify issues. Here's what they represent and how we use them:

  • browser bug - Issues that are reported to us, but actually are the result of a browser-specific bug. These are diagnosed with reduced test cases and result in an issue opened on that browser's own bug tracker.
  • confirmed - Issues that have been confirmed with a reduced test case and identify a bug in Inkline.
  • css - Issues due to our compiled CSS or source Sass files.
  • js - Issues stemming from our compiled or source JavaScript files.
  • docs - Issues for improving or updating our documentation.
  • feature - Issues asking for a new feature to be added, or an existing one to be extended or modified. New features require a minor version bump (e.g., v1.0.0 to v1.1.0).
  • help wanted - Issues where we need or would love help from the community to resolve.
  • meta - Issues with the project itself or our GitHub repository.

For a complete look at our labels, see the project labels page.

Bug reports

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful, so thanks!

Guidelines for bug reports:

  1. Provide a clear title and description of the issue.
  2. Share the version of Inkline you are using.
  3. Add code examples to demonstrate the issue. You can also provide a complete repository to reproduce the issue quickly.

A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report:

  • What is your environment?
  • What steps will reproduce the issue?
  • What browser(s) and OS experience the problem?
  • Do other browsers show the bug differently?
  • What would you expect to be the outcome?

All these details will help us fix any potential bugs. Remember, fixing bugs takes time. We're doing our best!

Example:

Short and descriptive example bug report title

A summary of the issue and the browser/OS environment in which it occurs. If suitable, include the steps required to reproduce the bug.

  1. This is the first step
  2. This is the second step
  3. Further steps, etc.

<url> - a link to the reduced test case

Any other information you want to share that is relevant to the issue being reported. This might include the lines of code that you have identified as causing the bug, and potential solutions (and your opinions on their merits).

Reporting upstream browser bugs

Sometimes bugs reported to us are actually caused by bugs in the browser(s) themselves, not bugs in Inkline per se. When feasible, we aim to report such upstream bugs to the relevant browser vendor(s), and then list them on our Wall of Browser Bugs and document them in MDN.

Vendor(s) Browser(s) Rendering engine Bug reporting website(s) Notes
Mozilla Firefox Gecko https://bugzilla.mozilla.org/enter_bug.cgi "Core" is normally the right product option to choose.
Apple Safari WebKit https://bugs.webkit.org/enter_bug.cgi?product=WebKit
https://bugreport.apple.com		 In Apple's bug reporter, choose "Safari" as the product.
Google, Opera Chrome, Chromium, Opera v15+ Blink https://code.google.com/p/chromium/issues/list Click the "New issue" button.
Microsoft Edge EdgeHTML https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/

Feature requests

Feature requests are welcome! When opening a feature request, it's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible.

When adding a new feature to the library, make sure you update the documentation package as well.

Testing

Before providing a pull request be sure to test the feature you are adding. Inkline's target code coverage is 100% and we're proudly consistent with that.

Coverage Status

Pull requests

Good pull requests—patches, improvements, new features are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

Please ask first before starting on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you might spend a lot of time working on something that the project's developers might not want to merge into the project.

Please adhere to the coding guidelines used throughout the project (indentation, accurate comments, etc.) and any other requirements (such as test coverage).

Do not edit inkline.css, or inkline.js directly! Those files are automatically generated. You should edit the source files in /src instead.

Similarly, when contributing to Inkline's documentation, you should edit the documentation source files in the /src directory.

Adhering to the following process is the best way to get your work included in the project:

  1. Fork the project, clone your fork, and configure the remotes:

    # Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/inkline.git

# Navigate to the newly cloned directory
cd inkline

# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/inkline/inkline.git

  2. Create a new topic branch (off the main project branch) to contain your feature, change, or fix:

    git checkout -b <topic-branch-name>

  3. Make sure your commits are logically structured. Please adhere to these git commit message guidelines. Use Git's interactive rebase feature to tidy up your commits before making them public.

  4. Locally rebsase the upstream main branch into your topic branch:

    git pull --rebase upstream main

  5. Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  6. Open a Pull Request with a clear title and description against the main branch.

Important! By submitting a patch, you agree to allow the project owners to license your work under the terms of the MIT License (for code changes) and under the terms of the Creative Commons Attribution 3.0 Unported License (for documentation changes).

Code guidelines

HTML

Adhere to the linting and Code guidelines.

  • Use tags and elements appropriate for an HTML5 doctype (e.g., self-closing tags).
  • Use WAI-ARIA attributes in documentation examples for better accessibility.

Sass

Adhere to the linting and RSCSS guidelines.

JS

Adhere to the linting guidelines.

  • Use semicolons
  • 4 spaces (no tabs)
  • strict mode

Vue

Adhere to the linting and Concepts guidelines.

  • Prefix Inkline components with the I character
  • Provide multiple customization options
  • Use mixins where applicable

Local Development

  1. First, fork the repository and create a branch as specified in the Pull Request Guidelines above.

  2. You'll find a well-structured Vite.js + Vue.js project.

  3. Run npm install to install all dependencies.

  4. To start developing, run npm run dev in your command line to run Inkline in development mode. The documentation will be automatically generated based on the UI library updates.

  5. To test, run npm run test:dev to run the UI Library tests in development mode. Make sure you run npm run test to run all the tests once before creating a pull request.

License

By contributing your code, you agree to license your contribution under the MIT License. By contributing to the documentation, you agree to license your contribution under the Creative Commons Attribution 3.0 Unported License.