Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (124 loc) · 8.56 KB

CONTRIBUTING.md

File metadata and controls

181 lines (124 loc) · 8.56 KB
Raw

Please note! The github issue tracker should only be used for feature requests and bugs with a clear description of the issue and the expected behaviour (see below). All questions belong on Slack, StackOverflow or Google groups.

Issues

Issues are always very welcome - after all, they are a big part of making sequelize better. However, there are a couple of things you can do to make the lives of the developers much, much easier:

Tell us:

  • What you are doing?
    • Post a minimal code sample that reproduces the issue, including models and associations
    • What do you expect to happen?
    • What is actually happening?
  • Which dialect you are using (postgres, mysql etc)?
  • Which sequelize version you are using?

When you post code, please use Github flavored markdown, in order to get proper syntax highlighting!

If you can even provide a pull request with a failing unit test, we will love you long time! Plus your issue will likely be fixed much faster.

Pull requests

We're glad to get pull request if any functionality is missing or something is buggy. However, there are a couple of things you can do to make life easier for the maintainers:

  • Explain the issue that your PR is solving - or link to an existing issue
  • Make sure that all existing tests pass
  • Make sure you followed coding guidelines
  • Add some tests for your new functionality or a test exhibiting the bug you are solving. Ideally all new tests should not pass without your changes.
    • Use promise style in all new tests. Specifically this means:
      • don't use EventEmitter, QueryChainer or the success, done and error events
      • don't use nested callbacks (use arrow functions or variables to maintain context in promise chains)
      • don't use a done callback in your test, just return the promise chain.
    • Small bugfixes and direct backports to the 1.7 branch are accepted without tests.
  • If you are adding to / changing the public API, remember to add API docs, in the form of JSDoc style comments. See section 4a for the specifics.
  • Add an entry to the changelog, with a link to the issue you are solving

Still interested? Coolio! Here is how to get started:

1. Prepare your environment

Here comes a little surprise: You need Node.JS.

The development Node version is pinned in .node-version, which fnm, nvm, mise and asdf all read. CI's non-matrix jobs use the same file. Any Node satisfying engines in package.json works.

This repository uses pnpm, pinned by the packageManager field in package.json. Install any pnpm 12 (for example npm install -g pnpm@12) and it will switch itself to the pinned version inside the repo.

pnpm does not resolve packages published less than a day ago (its default minimumReleaseAge). That is deliberate supply-chain protection, so a version you just saw announced may not install yet.

2. Install the dependencies

Just "cd" into sequelize directory and run pnpm install, see an example below:

$ cd path/to/sequelize
$ pnpm install

pnpm-lock.yaml is committed, so this gives you the same dependency tree CI uses. If you change anything in package.json, commit the updated lockfile alongside it — CI installs with --frozen-lockfile and will fail if the two disagree.

The libpq package (via pg-native) compiles native bindings. pnpm only runs its build script because it is listed under allowBuilds in pnpm-workspace.yaml; if you add another dependency that needs a build step, it has to be added there too or pnpm install will fail.

3. Database

3.a Local instances

For MySQL and PostgreSQL you'll need to create a DB called sequelize_test. For MySQL this would look like this:

$ echo "CREATE DATABASE sequelize_test;" | mysql -uroot

CLEVER NOTE: by default, your local MySQL install must be with username root without password. If you want to customize that, you can set the environment variables SEQ_DB, SEQ_USER, SEQ_PW, SEQ_HOST and SEQ_PORT.

For Postgres, creating the database and (optionally) adding the test user this would look like:

$ psql

# create database sequelize_test;
# create user postgres with superuser;

3.b Docker

Makes sure docker and docker-compose are installed.

If running on macOS, install Docker for Mac.

Now launch the docker mysql and postgres servers with this command (you can add -d to run them in daemon mode):

$ docker-compose up postgres-95 mysql-57

4. Running tests

All tests are located in the test folder (which contains the lovely Vitest tests).

$ pnpm run test-all || test-mysql || test-sqlite || test-mssql || test-postgres || test-postgres-native

$ # alternatively you can pass database credentials with $variables when testing
$ DIALECT=dialect SEQ_DB=database SEQ_USER=user SEQ_PW=password pnpm test

For docker users you can use these commands instead

$ DIALECT=mysql pnpm run test-docker # Or DIALECT=postgres for Postgres SQL

# Only integration tests
$ DIALECT=mysql pnpm run test-docker-integration

5. Commit

Sequelize follows the AngularJS Commit Message Conventions. Example:

feat(pencil): add 'graphiteWidth' option

Commit messages are used to automatically generate a changelog, so make sure to follow the convention. If you are unsure, you can let commitizen ask you questions and commit for you (just run node_modules/.bin/git-cz). When you commit, your commit message will be validated automatically with validate-commit-msg.

Then push and send your pull request. Happy hacking and thank you for contributing.

Coding guidelines

Have a look at our .eslintrc.json file for the specifics. As part of the test process, all files will be linted, and your PR will not be accepted if it does not pass linting.

Publishing a release (For Maintainers)

This fork is not published to a registry. Consumers install it straight from a git tag, so cutting a release means tagging — there is no publish step.

  1. Ensure the latest build on develop-v4 is green
  2. Ensure your local code is up to date (git pull origin develop-v4)
  3. pnpm version patch|minor|major (see Semantic Versioning) — this bumps package.json and creates the vX.Y.Z tag
  4. git push origin develop-v4 --follow-tags
  5. Bump the pinned tag in the consumer, e.g. in auditboard-backend's pnpm-workspace.yaml catalog: "sequelize": "github:soxhub/sequelize#vX.Y.Z"

The tag is the only thing consumers see. Commits pushed to develop-v4 after the most recent tag are not shipped, no matter how long they have been on the branch. If a fix needs to go out, it needs a new tag and a matching bump on the consumer side.

What gets shipped

The files array in package.json is the single source of truth for package contents: lib, index.js, index.d.ts, plus package.json/README.md/LICENSE, which are always included. There is deliberately no .npmignore — when files is present it overrides .npmignore entirely, so having both meant one of them was dead config that still looked authoritative.

If you add a new top-level file or directory that consumers need, add it to files. Nothing else will include it. Verify with pnpm pack and inspect the tarball.

Do not add a build step

This package ships raw lib/ — there is deliberately no prepare, prepack, or build script, and adding one is a breaking change for consumers. Because the package is fetched as a GitHub tarball, a build script forces pnpm off that fast path into clone-and-build, and trips pnpm's build gate: every consuming repo would have to add sequelize to its own allowBuilds (onlyBuiltDependencies on pnpm 10) before it would install at all.

If a build step ever becomes genuinely necessary, publish to a private registry instead.