There are many ways to contribute to Mockoon: opening bugs or issues, submitting pull requests, suggesting new features, etc. All contributions are welcome but, please note that Mockoon promise is to be simple, easy to use, and fast. So, not all features are worth implementing and the maintainers may choose not to implement features that are out of Mockoon's scope, too complicated (especially UX wise) or, that didn't gather enough attention from the community. But we are open to discussion :)
You can always discuss your ideas or ask for support on the official community.
The following rules apply to all contributions:
- Always search among the opened and closed issues. Assigned issues are already being worked on, and, most of the time, cannot be reassigned.
- Bug reports, enhancements, and features must be discussed with the maintainers regarding the implementation, changes to the UI, etc.
- Pull requests must refer to an open issue. Pull requests not solving existing issues may not be accepted.
- Issues and PR must follow the provided templates.
- Check for opened unassigned issues or open a new one (after searching for closed issues).
- If you are not the issue creator, comment on the issue and request to work on it so it can be assigned to you.
- After discussing the implementation, the issue will be assigned to you by a maintainer. As a rule, the assignee is the person working on the issue.
Please respect this workflow to ensure that:
- Your work is in line with Mockoon roadmap.
- It hasn't been already done/rejected.
- There is only one person at a time working on an issue.
Mockoon is using a monorepo setup (with Lerna). We have 4 packages in the ./packages/
folder:
Libraries used by the desktop application and the CLI:
- @mockoon/commons: this library contains mostly typings, utils and migrations designed to be used in both the browser and Node.js environments. Thus, it is safe to use in the desktop Electron's main or renderer processes, and the CLI.
- @mockoon/commons-server: this library contains mostly "server side" code designed to be used in a Node.js environment. Thus, it is safe to use it in the desktop application Electron's main process and the CLI, but not in the desktop application Electron's renderer process.
Applications:
- @mockoon/cli; the CLI built with Oclif
- @mockoon/serverless; the package to run Mockoon as a serverless function (AWS lambda, etc.)
- @mockoon/desktop: the desktop application built with Electron and Angular (for the renderer process)
Prepare the repository:
- Clone the repository:
git@github.com:mockoon/mockoon.git
. - Install the dependencies and create internal symlinks:
npm run bootstrap
. - Build the 2 libraries:
npm run build:libs
. You can also build them in watch mode withnpm run build:libs:watch
.
For the CLI:
- Build the CLI:
npm run build:cli
. - Test CLI's command by running
./packages/cli/bin/run {command} args
where "command" is a CLI command likestart
,stop
, etc.
For the desktop application:
- Build the application processes (Electron main and renderer processes)
npm run build:desktop:dev
or in watch modenpm run build:desktop:dev:watch
. - Start the application with
npm run start:desktop:dev
. The application will restart automatically when you make changes to thecommons
orcommons-server
libraries or to the desktop application's code.
To debug the desktop application, you can use the VSCode launch configuration Desktop: All processes
(You need to stop the npm run start:desktop:dev
command). It will start the application in debug mode and attach the debugger to it. You will then be able to set breakpoints in VSCode on the desktop application's code and on the libraries code (commons
or commons-server
).
- Start your
feature
orfix
frommain
- Cover it with automated tests. You will find them in the
test
folders of each package. Please try to cover at least the easiest test cases of your feature. - Preferably squash your commits, except when it makes sense to keep them separate (one refactoring + feature development)
- Do not forget to add "Closes #xx" in one of the commit messages or in the pull request description (where xx is the GitHub issue number).
Branches naming convention:
- features and enhancements:
feature/{issue_number}-description
- bug fixes:
fix/{issue_number}-description
- chores:
chore/{issue_number}-description
When a feature or bugfix requires a change in the data model (Environment
, Route
, RouteResponse
, etc.) you must add a new migration:
- Add a new migration function in the @mockoon/commons library
./packages/commons/src/libs/migrations.ts
file. - Add a new test for the migration in the same library
./packages/commons/test/data/migrations/{MIGRATION_ID}/environments.json
and./packages/commons//test/suites/migrations.spec.ts
files. - Use the script
./packages/desktop/scripts/migrate-tests.js
in the desktop package in order to migrate the tests'environments.json
samples to the latest migration. Please note that some folders/sample files are excluded from the migration on purpose.
ESLint rules and Prettier code styling are enforced by the continuous integration pipeline. Please fix all the ESLint issues and format your code using Prettier before pushing.
Some unit and integration tests are present in the 4 packages. First you need to build the following 4 packages:
npm run build:libs
.npm run build:serverless
.npm run build:cli
.npm run build:desktop:ci
.
After the packages are build, you can run the tests necessary to your changes:
npm run test:commons
npm run test:commons-server
npm run test:libs
npm run test:serverless
npm run test:cli
npm run test:desktop
npm run test:desktop:packaged:win
npm run test:desktop:packaged:mac
npm run test:desktop:packaged:linux
All tests will also be run on each commit or pull request in the CI environment.
Open a pull request to be merged in the main
branch. All branches should start from main
and must be merged into main
. Ask one maintainer to review the code.
- Increment the version (which follows semver) in each package.json file depending on the changes, using
npm run set-versions
. To ignore a package give it the same version. Lerna will take care of increasing the internal dependencies version numbers. - Push.
Versions are synchronized between the desktop application, CLI and the libraries. We release all of them at the same time with a major version bump when a data migration is included in the relase, or when new common features are added (common = feature working in both desktop and CLI). The libraries can be released independently from the desktop application for minor and patch versions when the changes are only affecting the libraries.
Desktop application's process:
/!\ Respect the desktop tag format
vx.x.x
and the GitHub release creation as the desktop application automated update depends on it.
- Create a GitHub release targeting the
vx.x.x
tag.
/!\ Mark the release as a pre-release, and only set it as a final release when all binaries are successfully build, tested and uploaded. Otherwise, it will trigger the auto-update for versions <1.19.0.
The desktop Electron application will be packaged using the local symlinked libraries. So, the desktop's release can be independent from the libraries release.
The GitHub workflow will automatically package the application for different platforms with npm run package:win|mac|linux
. Including Windows/macOS code signing and notarization. Code signing is currently managed by @255kb.
Binaries will be saved as Actions artifacts.
-
Manually test the binaries if needed (changes not covered by automated tests).
-
Upload the artifacts binaries to the new GitHub release.
-
Publish the release (remove the "pre-release" label).
Libs' process (commons, commons-server, serverless, CLI):
Create a libs-vx.x.x
tag to automatically release all the libraries on NPM (commons, commons-server, serverless, CLI).
/!\ Do not create a GitHub release for the libs, as desktop versions <=1.19.0 relies on https://api.github.com/repos/mockoon/mockoon/releases/latest to get the latest release version. As we are using a monorepo, this would mess up the legacy auto update from the desktop application.
Some manual steps are required in order to properly distribute the application:
- the API repository (private) desktop release files must be updated. This will update the download links on the website.
- A pull request must be created to update Homebrew Cask repository (update the
version
and thesha256
hash in theCasks/mockoon.rb
file and open a PR). - Binary must be uploaded to the Snap store manually with
snapcraft upload --release=stable ./mockoon-{version}.snap
command. - Arch Linux repository must be updated (Docker image and script can be used in
./scripts/aur-version-bump
). - Chocolatey package should be automatically updated after some days.