Contributing

How to make a contribution

  1. Click the "Fork" button on this library's GitHub pageopen in new window to make a copy of the repository in your account which you can work on.
  2. Clone your forked repo to your computer.
  3. Move into the root of this project's directory and run npm install to get all dependencies installed; this will also set up Husky commit hooks automatically.
  4. Start coding! Check out the "I want to..." sections below for guidance on where to start.
  5. Once you are confident that your work is done, push your changes up to your repository and click "Contribute" > "Open pull request". Fill out a description of your changes and then create the pull request.
  6. A maintainer will review your code and may give feedback on anything that should be changed. Once tests are passing and your changes are approved, they will be merged into the main repository and automatically deployed via CircleCI using semantic-releaseopen in new window.

Thank you so much for your contribution ❤️

Commit messages

This library strictly enforces following the Angular commit guidelinesopen in new window for commit messages.

To make things as easy as possible, it is recommended that you run npm run commit to commit staged changes; this will open Commitizenopen in new window, a CLI tool which will walk you through writing your commit message and handle all of the formatting for you.

However, if you prefer to manually write the commit message yourself, it should follow the following structure:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Accepted commit types

This library uses semantic-releaseopen in new window to determine how the package version should be incremented based on your commit message's type.

TypeDescriptionPackage Version Increment
featA new featureMinor version (+0.1.0)
fixA bug fixPatch version (+0.0.1)
refactorA code change that neither fixes a bug nor adds a featureMinor version (+0.1.0)
perfA code change that improves performanceMinor version (+0.1.0)
docsDocumentation only changesNo change unless the commit scope is readme, in which case it will publish a patch version (+0.0.1)
styleChanges that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)No change
testAdding missing or correcting existing testsNo change
choreChanges to the build process or auxiliary tools and libraries such as documentation generationNo change

Breaking changes

If your commit contains breaking changes from the current package version (ie, removes a prop, fundamentally changes how a feature works, etc), the commit message needs to be marked as such. To do so, add "BREAKING CHANGE: [description of breaking change]" to the footer of your commit message. This will result in the package being incremented by a major version (+1.0.0).

I want to update documentation

All documentation can be found in the docs directory.

The documentation site at https://react-hover-video-player.devopen in new window uses VuePressopen in new window to automatically construct a site with pages based on the README.md and CONTRIBUTING.md files' contents.

To preview the documentation site locally, run npm run docs:dev to serve it at http://localhost:8080open in new window.

When committing changes to the README, make sure you use the appropriate commit type and scope. Semantic-release normally skips commits of type docs, but this can result in the npm package page's README not getting updated to reflect changes that have been made to it.

If the main purpose of your commit is to update the README, please use docs as your commit's type and readme as the scope; this indicates to semantic-release that the change should be published to the npm package as a patched version. An example commit message might look like docs(readme): fix typo in readme.

I want to fix a bug or add a feature

All component code can be found in the src directory.

The HoverVideoPlayer component is defined in the src/component/HoverVideoPlayer.tsx file, so it is recommended that you start there.

Automated testing

This library uses Cypress component testsopen in new window for automated testing; all test files can be found in the tests/cypress/component directory.

  • npm run test will run all tests once and check the tests' code coverage. 100% code coverage is required. If you make a change, you must add a test accordingly.
    • To run a specific test file, use the --spec flag like so: npm run test -- --spec tests/cypress/component/testFile.spec.tsx
    • To only run a single test within a specific test file, change it() to it.only() for the desired test
  • npm run test-runner will open the Cypress test runner; this will provide a nice interface which helps with debugging and will automatically re-run tests as you make changes.
  • npm run test:smoke will perform a production build and then run all tests against the built code in a Chrome browser window. This can be used to catch potential problems introduced by the rollup config, but is otherwise slower to run and therefore not recommended for usage during regular development.

Development playground

Along with automated tests, you can also test your changes in a live demo playground environment located in the dev directory.

Running npm run dev will serve the contents of dev/index.tsx at http://localhost:3000open in new window with hot reloading.

For the most part, you will likely want to focus on editing the TestComponent.tsx file when testing your changes. You may modify playground files however you want for testing purposes, but your changes should not be committed. That being said, if you think your changes really should be committed, you are welcome to make a case for it!

Other miscellaneous things

  1. Make a new sandbox in CodeSandbox (for an easy head start, fork this sandboxopen in new window).

  2. Once the example is set up, make a screen recording.

    • On Macs, QuickTime Player is a decent option for making quick screen recordings
    • Try to keep the recording short and loop-friendly if possible (ie, start and end with the mouse cursor off the screen)
  3. Convert the recording to a .gif file

    • To guarantee the gif comes out with a good balance between file size and quality, it's recommended to use the following ffmpeg command for conversion:
    ffmpeg -i path/to/original-recording.mp4 -vf "fps=10,scale=1024:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output/demo.gif
    

    (special thanks to llogan's very helpful answeropen in new window which this command is based on)

  4. Add the .gif file to the README

    • Put the .gif file in the docs/assets/images directory.
    • Add ![alt text](./assets/images/your_file_name.gif)] to the appropriate place in the README.
    • If you feel comfortable, please wrap the gif with a link to your CodeSandbox!
Last Updated:
Contributors: Ryan Geyer