adapt-authoring-core 1.3.4 → 1.3.6

package/adapt-authoring.json

@@ -2,29 +2,27 @@
   "module": false,
   "documentation": {
     "enable": true,
-    "manualCover": "docs/cover-manual.md",
     "manualIndex": "docs/index-manual.md",
     "sourceIndex": "docs/index-backend.md",
     "manualPages": {
       "binscripts.md": "reference",
       "contributing.md": "contributing",
+      "contributing-code.md": "contributing",
       "coremodules.md": "reference",
       "customising.md": "development",
       "folder-structure.md": "getting-started",
-      "git.md": "contributing",
       "hooks.md": "concepts",
       "licensing.md": "reference",
-      "peer-review.md": "contributing",
       "releasing.md": "contributing",
+      "request-response.md": "concepts",
       "run.md": "getting-started",
-      "writing-a-module.md": "development",
-      "writing-core-code.md": "contributing"
+      "writing-a-module.md": "development"
     },
     "manualPlugins": [
       "docs/plugins/binscripts.js",
       "docs/plugins/coremodules.js",
-      "docs/plugins/index-manual.js",
+      "docs/plugins/contributors.js",
       "docs/plugins/licensing.js"
     ]
   }
-}
+}

package/docs/contributing-code.md

@@ -0,0 +1,192 @@
+# Contributing code
+
+This guide covers everything you need to know about contributing code to the Adapt authoring tool repositories.
+
+## Quick navigation
+
+- [Finding work](#finding-work)
+- [Setting up](#setting-up)
+- [Making changes](#making-changes)
+- [Documentation](#documentation)
+- [Commit messages](#commit-messages)
+- [Submitting a pull request](#submitting-a-pull-request)
+- [Code review](#code-review)
+
+## Finding work
+
+Pick an issue from one of the [adapt-security](https://github.com/adapt-security) repositories, or create a new one if you've found a bug or have a feature idea.
+
+### Difficulty labels
+
+Issues are labelled with difficulty ratings to help you find suitable work:
+
+| Label | Description |
+|-------|-------------|
+| `D: beginner` | Simple fixes, good for first-time contributors |
+| `D: easy` | Straightforward changes with limited scope |
+| `D: medium` | Moderate complexity, requires Node.js experience |
+| `D: hard` | Complex changes spanning multiple areas |
+| `D: insane` | Major architectural changes, requires deep codebase knowledge |
+
+If you're new to the project, start with `D: beginner` or `D: easy` issues. For larger features or complex fixes, please discuss your approach with the core team before starting work.
+
+## Setting up
+
+### Fork or branch?
+
+**Core team members** have write access to the repositories and can create branches directly.
+
+**External contributors** should fork the repository to their own GitHub account and work from there.
+
+### Create a branch
+
+Create a branch for your work, named after the issue number:
+
+```bash
+# For core team (direct branch)
+git checkout -b issue/1234 origin/master
+
+# For external contributors (from your fork)
+git checkout -b issue/1234
+```
+
+Always branch from `master` — this is the only long-lived branch.
+
+## Making changes
+
+### Code style
+
+All code must pass the [Standard.js](https://standardjs.com/) linter. Run it locally before committing:
+
+```bash
+npx standard
+```
+
+### Tests
+
+If you're adding new functionality, add tests to cover it. Run the test suite to make sure everything passes:
+
+```bash
+npm test
+```
+
+### Documentation
+
+Keep documentation up to date with your changes:
+
+- **Code comments** — Add or update JSDoc comments for any new or modified functions, classes, or methods
+- **Manual pages** — If you're adding a feature or changing behaviour, update the relevant markdown guides in `docs/`
+- **REST API** — For API changes, ensure route metadata is accurate so the generated API docs stay current
+
+Good documentation helps others understand and use your work. See [Writing Documentation](writing-documentation) for more details.
+
+
+## Commit messages
+
+We use [semantic-release](https://semantic-release.gitbook.io/) to automate releases, so commit messages must follow a specific format. The commit prefix determines the type of release:
+
+| Prefix | Release type | Use for |
+|--------|--------------|---------|
+| `Fix:` | Patch (0.0.x) | Bug fixes |
+| `Update:` | Minor (0.x.0) | New features, backwards-compatible changes |
+| `Breaking:` | Major (x.0.0) | Breaking changes |
+| `Docs:` | No release | Documentation only |
+| `Chore:` | No release | Maintenance, refactoring |
+
+### Format
+
+```
+Prefix: Short description
+
+Longer explanation if needed. Wrap at 72 characters.
+
+Closes #1234
+```
+
+### Examples
+
+```
+Fix: Prevent crash when uploading empty file
+
+The upload handler now validates file size before processing,
+returning a 400 error for empty files.
+
+Closes #1234
+```
+
+```
+Update: Add bulk delete endpoint for assets
+
+Closes #5678
+```
+
+```
+Breaking: Remove deprecated /api/v1 endpoints
+
+The v1 API has been removed. All clients should migrate to /api.
+
+Closes #9012
+```
+
+### Tips
+
+- Use the imperative mood ("Add feature" not "Added feature")
+- Keep the first line under 72 characters
+- Reference the issue number with `Closes #1234` to auto-close it when merged
+- For breaking changes, explain what users need to do to migrate
+
+## Submitting a pull request
+
+### Before submitting
+
+- [ ] Code passes linting (`npx standard`)
+- [ ] Tests pass (`npm test`)
+- [ ] Documentation is updated (if applicable)
+- [ ] Commit messages follow the format above
+- [ ] Branch is up to date with master
+
+### Creating the PR
+
+1. Push your branch to GitHub
+2. Open a pull request against the `master` branch
+3. Fill in the PR template, linking to the issue it addresses
+4. Request reviews from the core team
+
+For external contributors, submit the PR from your fork to the upstream repository.
+
+## Code review
+
+All code must be reviewed before merging.
+
+### Requirements
+
+For a PR to be merged:
+
+- **2 approvals required** — At least two reviewers must approve
+- **CI checks must pass** — Linting and tests must succeed
+- **No unresolved conversations** — All review comments must be addressed
+
+### Review criteria
+
+Reviewers will check that:
+
+- The code does what the issue describes
+- The implementation approach is sound
+- Code style follows project standards
+- Tests are included where appropriate
+- Documentation is added/updated where necessary
+- No negative side effects are anticipated
+- Commit messages follow the required format
+
+### Responding to feedback
+
+If changes are requested:
+
+1. Make the requested changes in new commits
+2. Push to the same branch (the PR updates automatically)
+3. Reply to review comments explaining what you changed
+4. Request re-review when ready
+
+### After approval
+
+Once approved, a core team member will merge your PR. Thanks for contributing! :tada:

package/docs/contributing.md

@@ -1,54 +1,45 @@
 # Contributing to the project
 
-First of all, thank you for showing interest in the Adapt project! We heartily welcome any contribution however big or small. This page outlines a few ways you can get involved.
+Thank you for your interest in contributing to the Adapt authoring tool! Whether you're fixing a bug, adding a feature, improving documentation, or just helping others in the community, your contribution is valued.
 
-## 1. Explore the community
+## Join the community
 
-The Adapt project has a thriving, friendly community who have an incredible knowledge of the inner-workings of Adapt - make as much use of this as you can. 
+The Adapt project has a friendly, knowledgeable community — make the most of it.
 
-### Say hello
+**Chat with us** — Drop by our [adapt-authoring room](https://gitter.im/adaptlearning/adapt-authoring) on Gitter to ask questions or say hello. For general Adapt discussion, there's also [general_chat](https://gitter.im/adaptlearning/general_chat). You'll need a GitHub account to join.
 
-If this is your first time contributing, please drop by our [general_chat](https://gitter.im/adaptlearning/general_chat) stream on Gitter and introduce yourself (you'll need a GitHub account to do this) - we love seeing new faces!
+**Visit the community site** — The [Adapt Learning community site](https://www.adaptlearning.org/) is the project hub, with forums, resources, and links to all corners of the project.
 
-For chat specifically related to the authoring tool, the [adapt-authoring room](https://gitter.im/adaptlearning/adapt-authoring) is the place to go.
-
-### Head to the community site
-
-The community site acts as the project hub; first and foremost providing you with links to all corners of the Adapt project, such as the issue tracker, and source code.
-
-At the heart of the community site are the forums, and one of the best ways you can contribute to the project is to share your knowledge of Adapt in here. The only requirement is that you like a chat!
-
-
-## 2. Find something to work on
-
-The next step to getting involved is to find something to actually work on. Based on your skills and interests, there are a number of different areas that you can help out with.
+## Ways to contribute
 
 ### Report issues
 
-One of the easiest ways to make a meaningful contribution to the project is to submit any bugs you find to the relevant repo:
-- [Adapt Framework](https://github.com/adaptlearning/adapt_framework/issues)
-- [Adapt authoring tool](https://github.com/adaptlearning/adapt-authoring/issues)
+Found a bug? Have an idea for a feature? Submit it to the relevant repository:
 
-If you think you've found a bug, check out our guide on [reporting issues](https://github.com/adaptlearning/adapt_framework/wiki/Bugs-and-features), which will give you more information on verifying your bug, as well as what to report, and where.
+- [Adapt authoring tool](https://github.com/adapt-security/adapt-authoring/issues)
+- [Adapt Framework](https://github.com/adaptlearning/adapt_framework/issues)
 
-If you can fix a bug you've reported, even better! Check out the next section on what to do in that case.
+Before submitting, search existing issues to avoid duplicates. When reporting bugs, include steps to reproduce, expected behaviour, and actual behaviour.
 
 ### Fix issues
 
-If you're looking to get involved as a developer, fixing existing issues is a good place to start.
+If you're a developer, fixing existing issues is a great way to contribute. Check out the issue trackers for bugs labelled with difficulty ratings:
 
-We've written a [guide to contributing code](writing-core-code) which will give you more information on finding a bug to work on, how to go about fixing that bug, and what to do once you've written a patch.
+- `D: beginner` / `D: easy` — Good starting points for newcomers
+- `D: medium` — For developers comfortable with Node.js
+- `D: hard` / `D: insane` — Complex issues requiring deep codebase knowledge
 
-### Contribute code
+See [Contributing Code](contributing-code) for the complete guide on submitting code changes.
 
-If you've been working with Adapt for a while, and are comfortable working with the framework on a larger scale, you may want to contribute to a larger feature-request patch (you can filter these in the issues page of the relevant repo), or [write your own module](writing-a-module).
+### Write documentation
 
-Have a look at our [page dedicated to code contribution](https://github.com/adaptlearning/adapt_framework/wiki/Contributing-code) for more.
+Clear documentation helps everyone. If you spot something that could be improved, or want to write new guides, we'd love your help. You don't need to be a developer — just a willingness to explain things clearly.
 
-### Write documentation
+### Help others
 
-If you're a keen writer, we're always looking for more hands to help out writing documentation (no technical knowledge necessary). See our [documentation guide](https://github.com/adaptlearning/adapt_framework/wiki/Writing-documentation) for more.
+Share your knowledge in the forums and chat rooms. Answering questions is one of the most valuable contributions you can make.
 
-## 3. Repeat!
+## Find us on GitHub
 
-Hopefully, you've been bitten by the open-source bug by now and want to contribute more. We always look forward to community contribution, no matter how small :grinning: 
+- [adapt-security](https://github.com/adapt-security) — Authoring tool repositories
+- [adaptlearning](https://github.com/adaptlearning) — Adapt Framework and community plugins

package/docs/plugins/index-manual.js

@@ -230,31 +230,28 @@ export default class Contributors {
 
       return `<div class="contributors-grid">\n${rows}\n</div>
       <style>
-      .contributors-grid {
-        margin: 0 auto;
-        max-width: 600px;
-        padding: 20px 0;
-      }
-
-      .contributors-row {
-        display: flex;
-        flex-wrap: wrap;
-        align-items: center;
-        justify-content: center;
-        gap: 4px;
-        margin-bottom: 12px;
-        text-align: center;
-      }
-
-      .contributors-grid a:hover {
-        transform: scale(1.1);
-      }
-
-      .contributor-avatar {
-        object-fit: cover;
-        vertical-align: middle;
-      }
-      </style>`
+.contributors-grid {
+  margin: 0 auto;
+  max-width: 600px;
+  padding: 20px 0;
+}
+.contributors-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  margin-bottom: 12px;
+  text-align: center;
+}
+.contributors-grid a:hover {
+  transform: scale(1.1);
+}
+.contributor-avatar {
+  object-fit: cover;
+  vertical-align: middle;
+}
+</style>`
     } catch (e) {
       console.error('Failed to generate contributors list:', e)
       return '<p>Unable to load contributors list.</p>'

package/docs/releasing.md

@@ -34,7 +34,7 @@ Releases follow [semantic versioning](https://semver.org/) (major.minor.patch).
 | `Breaking:` | Major (x.0.0) | Breaking changes |
 | `Docs:`, `Chore:` | No release | Documentation, maintenance |
 
-See [writing core code](writing-core-code.md) for detailed commit message guidelines.
+See [contributing code](contributing-code) for detailed commit message guidelines.
 
 ### Configuration
 

package/lib/Utils.js

@@ -54,16 +54,20 @@ class Utils {
       if (!options.cwd) options.cwd = ''
       App.instance.log('verbose', 'SPAWN', options)
       const task = spawn(options.cmd, options.args ?? [], { cwd: options.cwd })
-      let output = ''
+      let stdout = ''
+      let stderr = ''
       let error
       task.stdout.on('data', data => {
-        output += data
+        stdout += data
+      })
+      task.stderr.on('data', data => {
+        stderr += data
       })
       task.on('error', e => {
         error = e
       })
       task.on('close', exitCode => {
-        exitCode !== 0 ? reject(App.instance.errors.SPAWN.setData({ error: error ?? output })) : resolve(output)
+        exitCode !== 0 ? reject(App.instance.errors.SPAWN.setData({ error: error ?? stderr ?? stdout })) : resolve(stdout)
       })
     })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",

package/docs/git.md

@@ -1,41 +0,0 @@
-# Git process
-
-> This article assumes that you understand the [basic concepts of the git version control system](https://help.github.com/articles/good-resources-for-learning-git-and-github/)._
-
-### Overview
-
-The authoring tool core repository doesn't contain any code 
-
-We organise the branches in our repos in a similar way to standard [git flow](https://datasift.github.io/gitflow/IntroducingGitFlow.html), with a few alterations.
-
-### Branching
-
-We use the following branches:
-
-Name | Description | Persisting
----- | ----------- | ----------
-`master` | Contains the stable, released code. | yes
-`release/VERSION_NAME`<br/>*(e.g. `release/v1.0`)* | A release candidate branch. Contains **development** code, and should not be considered stable. Use this code at your own risk! | no
-`issue/TICKET_NAME` <br/>*(e.g. `issue/1024`)* | A self-contained bug-fix/feature. Should be named after a corresponding issue ID. Finished changes should be submitted as a pull request. | no
-
-We also apply the following rules:
-
-* The `master` branch is the only persisting branch. **All other branches should be deleted post-merge**.
-* The `master` branch contains only thoroughly tested code, and should only ever merge code from a `release` branch.
-* Any `issue` branches should be submitted as a PR to the current `release` branch (**NOT `master` -- unlike standard git flow, we don't allow hotfixes directly into `master`**).
-
-### Gearing up for release
-
-We go through the following schedule prior to making a release:
-
-1. The core development team assign a bunch of issues/features to the relevant release.
-2. A `release` branch is created from the master branch.
-3. The coders are let loose :dizzy_face::wrench:, and submit their additions as PRs using the [documented process](peer-review).
-4. Once all work has been done, we call a code freeze :snowflake: to avoid any scope-creep (i.e. only allow bug fixes from this point).
-5. The release branch goes through our testing process.
-6. Any bugs found are fixed :innocent:.
-7. Steps 5. and 6. are :repeat: as necessary.
-
-### Releasing
-
-Once the release code has been tested, we merge the release branch into `master`, tag the `master` branch with the release number, and **party**! :tada::balloon::tropical_drink:

package/docs/peer-review.md

@@ -1,51 +0,0 @@
-# Peer code review
-
-All code must go through a peer-approval process before it is merged with any of the collaborator-maintained codebases. This is to ensure that it firstly 'scratches' the intended 'itch', and complies to the guidelines set out by the project.
-
-## The Process
-
-When code is ready for review, the below process is followed:
-
-1. Code is submitted for review as a pull request.
-1. Code is then reviewed by peers using GitHub's [pull-request review](https://help.github.com/articles/about-pull-request-reviews/) feature to leave comments where necessary and give an approval/rejection.
-1. Code is amended if needed until it satisfies the required number of approvals.
-1. Provided all unit tests are passing, code is merged.
-
-## The Rules
-
-The reviewing process is governed by these rules:
-
-* The developer who submits the PR is not allowed to submit a review.
-* If a commit is added to the PR, any previously given reviews are invalidated. Everyone must re-post their verdicts after reviewing the commit.
-* Any new functionality/feature requests uncovered during review of a PR must be separated into new issues/PRs, unless directly related.
-* **For code to be merged, a minimum of three approvals is required. Of these, at least two must have come from a core team member. In the interest of impartiality, it is generally not advised to get all three approvals from a single collaborating company.**  
-* The person who merges the PR must also submit their review prior to merging **if their vote is required**. Merging a PR which already has enough approvals does not require the review of the merger themselves.
-* Any review rejections must be accompanied by an adequate explanation of why the PR should not be merged. Without this, the review will be disregarded.
-* Any concerns signalled by a 'rejected' review warrant careful consideration, but no reviewer has veto rights. If the PR receives enough approvals, it can still be merged (provided the other rules outlined on this page are followed).
-  1. Concerns will be resolved in conversation between the submitter of the PR and the reviewer who rejected the PR. When/if satisfied, the reviewer will change verdict to an approval.
-  2. At an impasse, a course of action will be decided by the core development team.
-
-## The Verdict
-
-There are two 'statuses' which can be applied to submitted PRs: **approve** and **request changes**. See below for a quick checklist for each:
-
-### Request changes.
-A core developer may reject a PR because any (or all) of the following:
-
-- The code fails testing.
-- The code does not meet Adapt standards.
-- The code negatively impacts the application.
-- There are unresolved questions about the intent of the code.
-
-### Approved.
-A core developer will approve an PR because of the following:
-
-- The intentions of the submitter are understood.
-- The implementation of the PR is accepted.
-- The submitted code complies with the code-style outlined in the project's [styleguide](https://github.com/adaptlearning/documentation/blob/master/01_cross_workstream/style_guide.md).
-- The code passes all automated tests.
-- No negative issues resulting from the proposed changes are forseen.
-
-## References
-
-[SmartBear: 11 Best Practices for Peer Code Review](http://smartbear.com/smartbear/media/pdfs/wp-cc-11-best-practices-of-peer-code-review.pdf)

package/docs/run.md

@@ -1,12 +0,0 @@
-# Running the application
-> You can find developer-specific instructions in the [developer install instructions](install-dev).
-
-To run the application, simply use the npm start script:
-```
-npm start
-```
-
-> Advanced users may also use the `NODE_ENV` environment variable to specify which configuration file is loaded with the application. This value is `production` by default.
-> You can read more about configuring your environment on [this page](configure-environment).
-
-The application will take a while to start up on the first boot, as it has various initialisation tasks to perform. Subsequent boots will be much quicker.

package/docs/writing-core-code.md

@@ -1,39 +0,0 @@
-# Writing core code
-
-We heartily welcome contributions to the source code for the Adapt authoring project. This document outlines a few tips to help you get started.
-## Finding work
-
-* Pick an open issue from the list [here.](https://github.com/adaptlearning/adapt-authoring/issues)
-* Create a new ticket for the issue you have noticed, following our guidelines on [submitting new bugs and features.](https://github.com/adaptlearning/adapt_framework/wiki/Bugs-and-features)
-  * If submitting a new ticket, we recommend getting the go-ahead for the change from the core team before you start work.
-
-### Use the labels
-
-We add difficulty rating labels to issues to give developers an idea of the work involved (always prefixed with `D:`). Picking up a `D: beginner` or `D: easy` issue is a good place to start if you're new to the project, and have limited Node.js and Backbone.js experience. For more confident developers, `D: medium` issues should be no problem. Any `D: hard` and `D: insane` issues are likely to involve very complex solutions, and potentially collaboration, to solve. Due to the work involved, these should only be attempted by developers with an extensive knowledge of the codebase, and a good working relationship with the core team.
-
-## Making Changes
-
-* Create a new branch for the issue that you are fixing:
-  * Make sure to base it on the correct parent branch; in most cases this will be develop. Getting this step wrong may cause you a lot of heartbreak when it comes to merging later on, so it's worth checking before starting work.
-  * Name your branch according to the issue it addresses (i.e. `issue/1234`).
-  * Create your branch (e.g. `git checkout -b issue/123 origin/develop`).
-* Make your changes (please make sure that your commit messages stick to the [guidelines](http://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines), and take advantage of GitHub's built in features to [close issues via commits.](https://help.github.com/articles/closing-issues-via-commit-messages/)
-* Add unit tests to cover your new functionality, if appropriate.
-* Run the existing unit tests using `npm test` (and ensure they pass!)
-
-## Submitting Changes
-
-### Checklist
-- Does it have an accompanying issue?
-- Does it have tests?
-- Does it pass the project's code standards?
-
-* Push your changes to your personal fork of the `adapt_authoring` repository.
-* Submit a pull request using the GitHub interface, and make sure to link to the issue you're addressing.
-* The core team will be automatically notified of your changes, but you can also bring it to our attention via the [gitter.im channel](https://gitter.im/adaptlearning/server-refactor).
-
-
-
-
-
-