Skip to content

Latest commit

 

History

History
184 lines (125 loc) · 7.4 KB

CONTRIBUTING.md

File metadata and controls

184 lines (125 loc) · 7.4 KB
Raw

Contributing

Thank you for investing your time in contributing to this project! Please take a moment to review this document in order to streamline the contribution process for you and any reviewers involved.

Read our Code of Conduct to keep our community approachable and respectable.

In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR

New contributor guide

To get an overview of the project, read the README. Here are some resources to help you get started with open source contributions:

Opening a Pull Request

To help the project's maintainers and community quickly understand the nature of your pull request, please be sure to do the following:

  1. Include a descriptive Pull Request title.
  2. Provide a detailed description that explains the nature of the change(s) introduced. This is not only helpful for your reviewer, but also for future users who may need to revisit your Pull Request for context purposes. Screenshots/video captures are helpful here!
  3. Make incremental, modular changes, with a clean commit history. This helps reviewers understand your contribution more easily and maintain project quality.

Checklist

Check to see that you have completed each of the following before requesting a review of your Pull Request:

  • All existing unit tests are still passing (if applicable)
  • Add new passing unit tests to cover the code introduced by your PR
  • Update the README
  • Update or add any necessary API documentation
  • All commits in the branch adhere to the conventional commit format: e.g. fix: bug #issue-number

Conventional Commit Spec

Commits should be in the format <type>(<scope>): <description>. This allows our team to leverage tooling for automatic releases and changelog generation. An example of a commit in this format might be: docs(readme): fix typo in documentation

type can be any of the follow:

  • feat: a feature, or breaking change
  • fix: a bug-fix
  • test: Adding missing tests or correcting existing tests
  • docs: documentation only changes (readme, changelog, contributing guide)
  • refactor: a code change that neither fixes a bug nor adds a feature
  • chore: reoccurring tasks for project maintainability (example scopes: release, deps)
  • config: changes to tooling configurations used in the project
  • build: changes that affect the build system or external dependencies (example scopes: npm, bundler, gradle)
  • ci: changes to CI configuration files and scripts (example scopes: travis)
  • perf: a code change that improves performance
  • style: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

scope is optional, and can be anything. description should be a short description of the change, written in the imperative-mood.

Example workflow

Follow this process if you'd like your work considered for inclusion 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 git@github.com:<YOUR_USERNAME>/vue.git
# Navigate to the newly cloned directory
cd vue
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/imgix/vue

  2. If you cloned a while ago, get the latest changes from upstream:

    git checkout <dev-branch>
git pull upstream <dev-branch>

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

    git checkout -b <topic-branch-name>

  4. Commit your changes in logical chunks. Use Git's interactive rebase feature to tidy up your commits before making them public.

  5. Locally merge (or rebase) the upstream development branch into your topic branch:

    git pull [--rebase] upstream <dev-branch>

  6. Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  7. Open a Pull Request with a clear title and description.

IMPORTANT: By submitting a patch, you agree to allow the project owner to license your work under the same license as that used by the project.

Project Goals

  • Provide a simple, easy-to-understand API that users can use to get started in the shortest time possible. This API should cover a large amount (~80%) of use cases of a normal img element without making the API surface too large or complicated.
  • Provide a separate, powerful, low-level API that gets out of the way to allow developers to use the imgix API in Vue how they like.
  • The code should be well-tested and of high quality.
  • The public API should be handled with care because a) once an API is submitted, we are committed to supporting it for a reasonable amount of time, and b) any changes to the API creates exponentially more work for the users of our libraries.

Using the issue tracker

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

  • Please do not derail or troll issues. Keep the discussion on topic and respect the opinions of others.

Development

The development of this library follows this very useful guide about Outside-In Frontend Development in Vue. I highly recommend at least becoming familiar with some of the core concepts of Outside-In TDD.

Publishing

Semantic-release will auto-publish anything that is merged into the next branch to npm under the next dist-tag. Users can install this version by running npm install @imgix/vue@next. To facilitate this, every commit must follow the conventional commit specification.

The current process to publish the main dist-tag from the main branch:

  1. Merge the latest changes from next
  2. Run yarn to install the latest deps
  3. Bump the package version in package.json and imgix-vue.ts by a patch version. This is important because if we release with the same version as what's on the next branch, it won't work.
  4. npm publish

Code Conventions

  1. Make all changes to files under ./src, not ./dist or ./es.
  2. Use Prettier for code formatting. Code will automatically be formatted upon submitting a PR.

Project setup

yarn install

Compiles and hot-reloads for development

yarn serve

Compiles and minifies for production

yarn build

Run your unit tests

yarn test:unit

Run your end-to-end tests

yarn test:e2e

Lints and fixes files

yarn lint

Customize configuration

See Configuration Reference.