adapt-authoring-core 1.3.1 → 1.3.3

package/adapt-authoring.json

@@ -2,16 +2,22 @@
   "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",
       "coremodules.md": "reference",
-      "customising.md": "advanced",
+      "customising.md": "development",
       "folder-structure.md": "getting-started",
-      "hooks.md": "basics",
+      "git.md": "contributing",
+      "hooks.md": "concepts",
       "licensing.md": "reference",
-      "writing-a-module.md": "basics",
+      "peer-review.md": "contributing",
+      "releasing.md": "contributing",
+      "run.md": "getting-started",
+      "writing-a-module.md": "development",
       "writing-core-code.md": "contributing"
     },
     "manualPlugins": [

package/docs/contributing.md

@@ -0,0 +1,54 @@
+# 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.
+
+## 1. Explore 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. 
+
+### Say hello
+
+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!
+
+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.
+
+### 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)
+
+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.
+
+If you can fix a bug you've reported, even better! Check out the next section on what to do in that case.
+
+### Fix issues
+
+If you're looking to get involved as a developer, fixing existing issues is a good place to start.
+
+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.
+
+### Contribute code
+
+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).
+
+Have a look at our [page dedicated to code contribution](https://github.com/adaptlearning/adapt_framework/wiki/Contributing-code) for more.
+
+### Write documentation
+
+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.
+
+## 3. Repeat!
+
+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: 

package/docs/cover-manual.md

@@ -0,0 +1,11 @@
+![](https://www.adaptlearning.org/wp-content/uploads/2015/11/home-icon-03.png)
+
+# Adapt authoring tool
+
+## Developer guides
+
+> Handy guides and how-to information to help understand and make use of the Adapt authoring tool APIs in a practical way.
+
+[<i class="material-icons">download</i> Install](install)
+[<i class="material-icons">settings</i> Configure](configuration)
+[<i class="material-icons">flight_takeoff</i> Run](run)

package/docs/git.md

@@ -0,0 +1,41 @@
+# 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/index-manual.md

@@ -1,11 +1,41 @@
-![](https://www.adaptlearning.org/wp-content/uploads/2015/11/home-icon-03.png)
+# Adapt Authoring Tool Developer guides
 
-# Adapt authoring tool
+Welcome to the technical documentation for the Adapt authoring tool — a web-based application for creating responsive, multi-device e-learning content built on the [Adapt Framework](https://github.com/adaptlearning/adapt_framework).
 
-## Developer guides
+The authoring tool provides a user-friendly interface for building courses without needing to write code, while its modular architecture gives developers the flexibility to extend and customise virtually every aspect of the system. Whether you're looking to build custom plugins, integrate with external services, or contribute to the core codebase, you're in the right place.
 
-> Handy guides and how-to information to help understand and make use of the Adapt authoring tool APIs in a practical way.
+## What makes it tick
 
-[<i class="material-icons">download</i> Install](install)
-[<i class="material-icons">settings</i> Configure](configuration)
-[<i class="material-icons">flight_takeoff</i> Run](run)
+The authoring tool is built on a few key principles:
+
+- **Modular by design** — The entire application is composed of discrete modules that can be swapped, extended, or replaced. Need custom authentication? Write an auth plugin. Want to store data differently? Create a new database adapter.
+
+- **Schema-driven** — Content types, validation rules, and UI forms are all defined using JSON schemas. This means you can add new content types or modify existing ones without touching application code.
+
+- **RESTful API** — Every feature is accessible via a comprehensive REST API, making it straightforward to integrate with other systems or build custom tooling.
+
+- **Built for collaboration** — Multi-user support with role-based permissions lets teams work together on courses with appropriate access controls.
+
+## About this documentation
+
+This documentation covers the technical side of the authoring tool — how it works under the hood and how to extend it. You'll find guides on writing custom modules, working with the database, creating schemas, and contributing to the project.
+
+If you're looking for help using the authoring tool to create courses, check out the user guides on the [Adapt Learning community site](https://www.adaptlearning.org/).
+
+## Where to start
+
+New to the codebase? Here are some good starting points:
+
+- **[Folder Structure](folder-structure)** — Get familiar with how the application is organised
+- **[Writing a Module](writing-a-module)** — Learn the basics of creating your own module
+- **[Schemas Introduction](schemas-introduction)** — Understand how schemas drive the application
+- **[Hooks](hooks)** — See how to tap into the application lifecycle
+
+## Get involved
+
+The Adapt authoring tool is open source and we welcome contributions. You can find the source code and report issues on GitHub:
+
+- [adapt-security](https://github.com/adapt-security) — Authoring tool repositories
+- [adaptlearning](https://github.com/adaptlearning) — Adapt Framework and community plugins
+
+<div class="big-text">Happy coding!</div>

package/docs/peer-review.md

@@ -0,0 +1,51 @@
+# 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/releasing.md

@@ -0,0 +1,56 @@
+# Releasing
+
+This guide explains how releases are managed for the Adapt authoring tool.
+
+## Overview
+
+The project uses two release mechanisms:
+
+- **Module releases** — Automated via semantic-release when changes are merged to master
+- **Main repository releases** — Manual, allowing for thorough testing between releases
+
+## Module releases
+
+Individual modules (e.g., `adapt-authoring-core`, `adapt-authoring-auth`) are released automatically using [semantic-release](https://semantic-release.gitbook.io/).
+
+### How it works
+
+When a pull request is merged to the `master` branch, the release workflow:
+
+1. Analyses commit messages to determine the release type
+2. Bumps the version in `package.json`
+3. Generates release notes from commit messages
+4. Creates a GitHub release
+5. Publishes the package to npm (via [trusted publishing](https://docs.npmjs.com/generating-provenance-statements))
+
+### Version numbers
+
+Releases follow [semantic versioning](https://semver.org/) (major.minor.patch). The version bump is determined by commit message prefixes:
+
+| Prefix | Release type | Example |
+| ------ | ------------ | ------- |
+| `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:`, `Chore:` | No release | Documentation, maintenance |
+
+See [writing core code](writing-core-code.md) for detailed commit message guidelines.
+
+### Configuration
+
+Each module's release behaviour is configured in `package.json`, with the GitHub Actions workflow defined in `.github/workflows/releases.yml`.
+
+## Main repository releases
+
+The main `adapt-authoring` repository is released manually. This allows for a comprehensive testing cycle before each release.
+
+### Release process
+
+1. **Update dependencies** — Bump all `adapt-authoring-*` modules to their latest versions
+2. **Testing** — Run the full test suite and perform manual testing
+3. **Version bump** — Update the version in `package.json`
+4. **Tag and release** — Create a git tag and GitHub release with release notes
+
+### Permissions
+
+Only users with collaborator status on the repository can publish releases.

package/docs/run.md

@@ -0,0 +1,12 @@
+# 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/package.json

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