package.json
workflow for native development with Reason/OCaml.
This README serves as a development documentation for esy. For user documentation refer to esy.sh documentation site.
The following snippet lists esy repository structured (omitting irrelevant or obvious items) with further explanations:
├── CHANGELOG.md
├── LICENSE
├── README.md
│
├── Makefile
│ Common tasks and workflows for esy development.
│
├── bin/esy
│ symlink (wrapper on Windows) for esy command, used for running tests
│
├── bin/esyInstallRelease.js
│ postinstall step for npm releases produced with `esy npm-release`
│ command. This is a built JS file which is developed in a separate flow
│ inside `esy-install-npm-release/` subdirectory (see below).
│
├── docs
│ esy end user documentation in markdown format.
│
├── dune
├── dune-project
│
├── esy
│ This dune library implements sandbox builder - a routine which builds
│ the enture dependency graph and provides other introspection APIs.
│
├── esy/bin
│ This dune executable implements "esy" command.
│
├── esy-solve
│ This dune library implements solver.
│
├── esy-install
│ This dune library implements installer.
│
├── esy-build-package
│ This dune library implements package builder. esy library uses this to
│ build each package.
│
├── esy-build-package/bin
│ This dune executable implements "esy-build-package" command.
│
├── esy-installer
│ Implementation of installation procedure defined with *.install files.
│ This re-implements opam-installer.
│
├── esy-install-npm-release
│ Sources for `bin/esyInstallRelease.js`.
│
├── esy-command-expression
│ Parser for #{...} syntax used in esy manifests.
│
├── esy-shell-expansion
│ A simple shell expansion.
│
├── esy-yarn-lockfile
│ Parser for a subset of yarn lockfile format.
│
├── esy-lib
│ A collection of utility modules shared between other libraries.
│
├── site
│ Sources for https://esy.sh
│
├── esy.lock
├── package.json
│
├── scripts
│
├── test
│ Unit tests.
│
├── test-e2e-slow
│ End-to-end test suite which takes a significiant amount of time.
│ We execute it on CI by placing `@slowtest` token in commit messages.
│
└── test-e2e
End-to-end test suite.
To make changes to esy
and test them locally:
% git clone git://github.com/esy/esy.git
% cd esy
% esy
% yarn
% node scripts/bootstrap.js
On Linux/macOS (soon on Windows too) you can run:
% make install-githooks
which will install git hooks which will do pre commit validation.
To test the esy
executable in development you can use bin/esy
.
bin/esyInstallRelease.js
is developed separately within the esy-install-npm-release/
directory.
Run:
% make bin/esyInstallRelease.js
to update the bin/esyInstallRelease.js
file with the latest changed, don't
forget to commit it.
Run:
% make test
There are two branches:
master
— the active development, we cut new versions out of there regularly.0.0.x
— maintainance branch for 0.0.x releases.0.2.x
— maintainance branch for 0.2.x releases.0.3.x
— maintainance branch for 0.3.x releases.
To make changes to esy.sh:
- Bootstrap site's dev environment:
% make site-bootstrap
- Run site locally:
% make site-start
- When you are happy with the changes:
% make site-publish
Issues are tracked at esy/esy.
esy is released on npm.
Because esy is written in OCaml/Reason and compiled into a native executable we need to acquire a set of prebuilt binaries for each supported platform (Windows, macOS and Linux). We employ CI servers (thanks Azure) to build platform specific releases.
The release workflow is the following:
-
Ensure you are on
master
branch and assuming you want to release the version currently defined inpackage.json
(see step 6.), run% make release-tag % git push && git push --tags
-
Wait till CI finishes its task and release
@esy-nightly/esy
package.You can test it manually.
-
Run
% make release-prepare
which downloads the nightly corresponding to the current commit working directory is at and "promotes" it to a release. It will create
_release/package
directory. -
Ensure release inside
_release/package
directory is ok.You can
cd _release/package && npm pack && npm install -g ./esy-*.tgz
to test how release installs and feels. -
Run
% make release-publish
to upload the release on npm.
Use
% make NPM_RELEASE_TAG=next release-publish
to publish the release under
next
tag (so users won't get it automatically but only explicitly requested). -
Bump version in
package.json
to the next patch version.We expect the next version to be mostly a patch version. In case you want to release new minor or major version you need to bump it before the release.