Contributing Guidelines

Contribute Code

Coding Conventions

Please be consistent with what already exists. New code should not produce any new errors/warnings when the commands below are run. New code that produces new errors/warnings may be rejected.

Run the following command to check your changes against our linters and unit tests:

npm run test

Javascript

The plugin uses the ESLint static analysis tool to enforce coding standards in the Javascript source. The plugin uses ESLint’s recommended ruleset in conjunction with Google’s Javascript style config (only without jsdoc) as well as some custom rules defined in the ESLint configuration file. There are exceptions for configuration files and examples set up to allow longer comments and undefined variables. Run this command to test all code changes:

npm run lint

Alternatively, run these commands to test any individual changes to the Javascript source, unit tests, examples, ESLint configuration file, Instanbul (nyc) configuration file, Stylelint configuration file and gulp.js configuration file:

npx eslint source/agjCalendar/jquery.agjCalendar.js
npx eslint tests/*.js
npx eslint examples/*.js
npx eslint eslint.config.js
npx eslint nyc.config.js
npx eslint stylelint.config.js
npx eslint gulpfile.js

CSS

The plugin uses the Stylelint static analysis tool to enforce coding standards in the CSS source. The plugin uses Stylelint’s standard config as well as some custom rules defined in the Stylelint configuration file. Run this command to test all code changes:

npm run lint

Alternatively, run these commands to test any individual changes to the CSS source:

npx stylelint source/agjCalendar/jquery.agjCalendar.css
npx stylelint source/agjCalendar/jquery.agjCalendar.themes.css

Minified Javascript and CSS

Prior to committing any changes, you should be generating updated minified Javascript and CSS files using gulp.js. The minifier scripts are defined in the gulp.js configuration file. Run this command to generate new minified files:

gulp

Unit Tests

The plugin uses jQuery’s QUnit framework to run unit tests. The tests are all located in qunit.js and can be run online in-browser at agjCalendar.agjjQuery.org/tests/index.html. All tests should continue to pass and all new features should ideally include unit tests. Run this command to execute all unit tests:

npm run qunit

Run this command to view code coverage:

npm run coverage

Online Documentation

The plugin’s online documentation is available at agjCalendar.agjjQuery.org. Please ensure the documentation is updated along with any code changes. All of the files used to generate the documentation are in the /documentation/agjCalendar.agjjQuery.org/ folder. The website is powered by GitHub Pages which uses Jekyll. Run this command to test the online documentation website locally if you have Jekyll installed:

jekyll serve

Submitting Changes

Please send a GitHub Pull Request with a clear list of what you’ve done (read more about pull requests). Please follow our coding conventions (above) and make sure all of your commits are atomic (one feature per commit). Please use our pull request template when submitting pull requests.

Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:

$ git commit -m "A brief summary of the commit
>
> A paragraph describing what changed and its impact."

Contribute Translations

Although the plugin has built-in support for 20 languages we do not have team members that speak all of these languages. If you spot a translation error within our existing code or have knowledge about a language you would like to add support for please submit a pull request with your changes. Because we want to take advantage of any multilingual volunteers if you know about a language but not how to submit a pull request you can submit details of what should change in an issue or discussion post and a team member will help get your changes submitted.

Contribute Financially

You can contribute financially by becoming a patron at patreon.com/agjopensource to support agjCalendar and other agjjQuery.org plugins.

Code of Conduct

In order to participate your behaviour must conform to our code of conduct.