-
Notifications
You must be signed in to change notification settings - Fork 0
Home
This wiki contains notes about the usage of our fork of knex - the kind of things you might find in a README or as additional notes on usage (plus, this keeps us from cluttering the README with unneeded merge conflicts when pulling in the lastest version from upstream).
If you're looking for the documentation for knex, you're looking for this page.
If you're looking for the GitHub wiki of the upstream knex project, you're trying to get to the wiki page on the upstream repo.
The purpose of this knex fork is to provide a location for us to maintain and host a version of knex with bug fixes that are critical for our projects. It also serves as a space for the active development of our fixes so that they can be contributed back to the upstream knex project. The intention is to shift to using the upstream project directly once the PRs containing our fixes are merged upstream. At that point, this repo will likely serve as a way for us to prepare any future fixes we may need to contribute upstream down the road.
To use this fork in your project, it is recommended to install this package as an alias for knex:
$ npm install knex@npm:@itdeptutahcountygovernment/knex
To use the package, you require it and use it as if it were the upstream package (since it is installed as an alias):
const knex = require('knex');or if using ESM import instead of require:
import knex from 'knex';There are a couple of special considerations to make when upgrading our forked version of knex in a project. See the upgrading page for details on how to make the needed changes for the upgrade.
When bugs in knex are encountered and must be fixed for a specific project, The patch-package NPM package can streamline this process. The patches made by this package are stored as regular git patch/diff files, which can be used to re-create the needed fixes in a new branch in this repository so that a PR to the upstream knex project can be submitted.
If a PR to upstream has not been merged and released by the time a second project needs an unmerged fix, creating a NPM package release containing the fixes can be considered if it looks like merging the needed functionality upstream will take long enough that more upcoming projects will need the fix, while incorporating the patch-package NPM package into the project (or project templates) is not feasible given the changes.
As soon as multiple patches for fixes that affect the same file need to be made before merging and releasing into upstream can be completed, a new NPM package release should be created and used by projects until the PRs are merged. Be sure to install the forked package under the knex alias using npm install knex@npm:@itdeptutahcountygovernment/knex to avoid needing to change imports. Generally, we should avoid altering the version number so that it gets ahead of the upstream project. In such cases where we must make a release before the upstream version changes, use the pre-release version component (ex. append -uc.1 to the package version). Re-publishing the version in the fork's npm packages is also an option if the package is not already in general use.