Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (80 loc) · 6.82 KB

CONTRIBUTING.md

File metadata and controls

115 lines (80 loc) · 6.82 KB
Raw

Contributing to jQuery loadJSON

Want to contribute to jQuery loadJSON? That's great! Contributions are most welcome! Here are a couple of guidelines that will help you contribute. Before we get started: Please note that this project is released with a Contributor Code of Conduct to ensure that this project is a welcoming place for everyone to contribute to. By participating in this project you agree to abide by its terms.

Overview

Development

You need Node.js 26 (the version is in .nvmrc, so nvm use picks it).

npm ci
npx playwright install chromium firefox webkit
npm test

npm test is the one command to run before sending a change. It lints (ESLint), checks formatting (Prettier), builds dist/ with Rollup, and runs the test suite in Chromium (with coverage, which must stay at 100%), Firefox and WebKit, plus the tests of the published files.

  • Edit src/, never dist/. dist/ and docs/examples/jquery.loadJSON.js are generated by npm run build but committed, and CI checks they match a fresh build, so commit them with your change.
  • npm run format fixes formatting.
  • Tests use Vitest browser mode and live in test/suite/. Name them by behavior (describe / it: "when X, it should Y") and keep Arrange, Act and Assert apart.
  • npm run test:e2e runs the end-to-end tests with Playwright.

jQuery versions

The suite runs against jQuery 3.7.1 by default. CI also runs it, and the end-to-end tests, against jQuery 1.7.2 (the oldest supported version), 3.7.1 and 4.0.0, each in Chromium, Firefox and WebKit. To run another version locally, set JQUERY_FILE:

JQUERY_FILE=node_modules/jquery4/dist/jquery.js npx vitest run --project suite-chromium
scripts/fetch-jquery.sh 1.7.2
JQUERY_FILE=.jquery/jquery-1.7.2.js npx vitest run --project suite-chromium

scripts/fetch-jquery.sh downloads jQuery 1.7.2, which npm does not ship as a file, and checks its hash.

Documentation and examples

The documentation is in docs/, and GitHub Pages serves it with the live examples in docs/examples/. To try the examples locally, serve docs/ over HTTP (for example npx serve docs); they load their data with Ajax, so opening the files directly does not work.

Contribution workflow

  1. Fork the repository in GitHub with the Fork button.
  2. Switch to a new branch (ie. new-feature), and work from there:
    git checkout -b new-feature
  3. Make your feature addition or bug fix.
  4. Send a pull request (PR). Bonus points for topic branches.
  • Please make sure all of your commits are atomic (one feature per commit).
  • Write commit messages in the Conventional Commits style, such as fix: keep the fragment when adding a link parameter, with a short body if the change needs one.
  • If your PR fixes a separate issue number, include it in the commit message.

Things to keep in mind

  • Smaller PRs are likely to be merged more quickly than bigger changes.
  • If it is a useful PR, it will get merged in eventually.
  • This project is using Semantic Versioning 2.0.0

Reporting a bug

So you've found a bug, and want to help us fix it? Before filing a bug report, please double-check the bug hasn't already been reported. You can do so on our issue tracker. If something hasn't been raised, you can go ahead and create a new issue with the following information:

  • Which version of the plugin are you using?
  • Which version of the jQuery library are you using?
  • What browsers (and versions) have you tested in?
  • How can the error be reproduced?
  • If possible, include a link to a JSFiddle or CodePen example of the error.

If you want to be really thorough, there is a great overview on Stack Overflow of what you should consider when reporting a bug.

It goes without saying that you're welcome to help investigate further and/or find a fix for the bug. If you want to do so, just mention it in your bug report and offer your help!

Contributing to an existing issue

Finding an issue to work on

We've got a few open issues and are always glad to get help on that front. You can view the list of issues here. (Here's a good article on how to find your first bug to fix).

Before getting to work, take a look at the issue and at the conversation around it. Has someone already offered to work on the issue? Has someone been assigned to the issue? If so, you might want to check with them to see whether they're still actively working on it.

If the issue is a few months old, it might be a good idea to write a short comment to double-check that the issue or feature is still a valid one to jump on.

Feel free to ask for more detail on what is expected: are there any more details or specifications you need to know? And if at any point you get stuck: don't hesitate to ask for help.

Making your contribution

We've outlined the contribution workflow here. If you're a first-timer, don't worry! GitHub has a ton of guides to help you through your first pull request: You can find out more about pull requests here and about creating a pull request here.

Feature Requests

  • You can request a new feature by submitting an issue.
  • If you would like to implement a new feature:
    • For a Major Feature, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
    • Small Features can be crafted and directly submitted as a Pull Request.

Additional info

Especially if you're a newcomer to Open Source and you've found some little bumps along the way while contributing, we recommend you write about them. Here's a great article about why writing about your experience is important; this will encourage other beginners to try their luck at Open Source, too!