Contributing code

In this document, we assume a basic working knowledge of Adapt. If you're completely new, we recommend you first check out the Framework in five minutes, then try creating your own course to learn the ropes.

What skills do I need?

The technology stack used in the Adapt framework is intended to be accessible to new developers. As such, you should recognise some, or all of the technologies/frameworks that Adapt uses. See below for a brief breakdown, as well as links to useful related resources:

Required

JavaScript (ES6+) and HTML: Adapt courses are web-apps, so it's essential that you're comfortable with modern JavaScript — arrow functions, destructuring, const/let, template literals, and ES modules are used throughout.

Backbone: In addition to giving the code an organised MV* structure, Backbone also adds a few nice bells and whistles such as a page routing system, and a very versatile events module.

JSX/React: As of Framework v5.12.0, JSX is the recommended templating approach for all new plugins and components. Handlebars is still supported for existing plugins, but new work should use JSX.

LESS/CSS: We use LESS-preprocessed CSS for the styling of all elements in Adapt. You'll need to be comfortable with LESS variables, mixins, and nesting, as well as core CSS concepts like flexbox and responsive design.

Beneficial

The following are supporting libraries and frameworks; not essential to know, but very useful nonetheless.

jQuery & Underscore: Both are bundled with Adapt and available at runtime, but new plugin code should prefer vanilla JS and ES6 equivalents. jQuery is still useful when calling jQuery-dependent framework APIs.

Grunt (Node.js): Grunt automates the build process — code compilation, minification, asset management, and JSON validation. Anyone contributing code will interact with the build system, so familiarity with Grunt and basic Node.js is helpful.

Finding something to work on

The first step contributing code to the project is to find an area that you want to work on - something that can be easier said than done.

If you already have something in mind - maybe you've found a bug, or there's a specific plugin you want to develop, great! Otherwise, we've written a few tips on our Bugs and features page on how you can get started.

Need help?

Whatever you're working on, feel free to open an issue in the relevant Adapt repository if you need help or want to discuss your approach — we're a friendly bunch, and love to help!

Working with Adapt

We've tried to make installing and running Adapt as painless as possible by providing the command line tool, which automates a lot of the more tedious tasks.

Installing

Before working on Adapt, you'll need to do a few things to make sure you've got all of the required tools and libraries.

Adapt has few pre-requisites, so if you haven't already, get up and running by following the install guide.

Submitting your code

So you've gotten yourself acquainted with the code and have something to contribute back. The next step is to show us what you've done!

We use GitHub's pull request (PR) model to merge changes into the framework. For those unfamiliar with this, head over to this section in GitHub's help archives for a good selection of articles on the topic.

Reason for PR'ing

You don't necessarily have to submit complete code when you create a PR for us to look at. The following are all valid reasons to open one:

• You have a bug fix
• You've implemented a new feature
• You've started fixing a bug/implementing a new feature, but are unsure how to continue
• You've started fixing a bug/implementing a new feature, but don't have time to contribute further

If your work is unfinished, don't worry. Pull requests are a great way to start a discussion and show the core team what you're working on, as well as get some advice on implementation before you've finished coding, saving you time in the long-run.

Before submitting

Before you submit a PR to us, there are a few hoops that we ask you to jump through in the interest of transparency:

• Does your code work? This may seem obvious, but if we can't test your code, it's not going to be merged. Please make sure that anything you submit actually works 😄
• Does your code have a related Github issue? It's important that we keep a paper-trail regarding work done on the project; this helps us to keep a track of what's going on, and allows us to plan and manage our available developer resource effectively. Please make sure that there's an accompanying Github issue to go with your PR, be it a bug fix, new feature, or anything else (see our page on reporting bugs for more information on this).
• Does your code comply to the Adapt code styleguide? To give everyone working on the project an easier ride, we like to keep the coding style consistent across the breadth of Adapt repositories. Please make sure yours also complies to our standards.
• Have you updated the documentation and schemas? If your change involves adding a new property to — or changing an existing property in — the JSON, then that change will likely need to be reflected in the documentation (README.md, example.json), the modern schema files (schema/*.schema.json), and properties.schema
• Have you considered testing? Where practical, contributions should include tests — Jest for unit tests and Cypress for end-to-end tests. At a minimum, ensure your changes don't break existing tests.
• Is your code accessible? Adapt components must meet WCAG 2.2 Level AA requirements. Use semantic HTML, ensure keyboard navigation works, and provide appropriate ARIA attributes for interactive elements.

Creating a good PR

Remember that the purpose of the pull request is to allow the other contributors to review what you have written. To this end, it's important that you have:

• included a reference to the related GitHub issue/feature request (ideally using the keyword technique)
• commented your commits well
• given a short overview of what you've done
• described the expected behaviour after the changes
• listed any steps that need to be taken to check the changes
• noted anything that should be ignored (e.g. a known issue that you are not addressing)
• included screenshots if necessary

Peer code review

After you have submitted your code, it will undergo a peer review process carried out by the core development team. You can read more about this here:

Adapt peer code review process.

Merging

When your code passes our peer review process, it's good to go! A member of the core team should be along shortly to merge the code. If this doesn't happen, feel free to give the team a gentle nudge by commenting on the PR.

Repeat!

If you've gotten this far, congratulations! 🎉 You're now a contributing member of the Adapt project! We greatly appreciate any time you can give to the project, however small you think it may be 😄