Skip to content

public / sequelize

Go to a project

不要怂，就是干，撸起袖子干！

Commit 20cd5d7e by Sid Committed by GitHub
Options

meta: update contributing guidelines and issue templates (#13039) 

Co-authored-by: Pedro Augusto de Paula Barbosa <papb1996@gmail.com>
1 parent 83090924
Inline Side-by-side
Showing with 187 additions and 151 deletions
.github/ISSUE_TEMPLATE/bug_report.md
......@@ -10,13 +10,17 @@ assignees: ''
<!--
If you don't follow the issue template, your issue may be closed.
Please note this is an issue tracker, not a support forum.
For general questions, please use StackOverflow or Slack:
For general questions, please use StackOverflow:
https://stackoverflow.com/questions/tagged/sequelize.js
-->
## Issue Description
## Issue Creation Checklist
### What are you doing?
[ ] I have read the [contribution guidelines](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.md)
## Bug Description
### SSCCE
<!--
We have a repository dedicated to make it easy for you to create an SSCCE.
......@@ -27,13 +31,34 @@ Please consider using it, everyone wins!
**Here is the link to the SSCCE for this issue:** LINK-HERE <!-- add a link to the SSCCE -->
<!--
If you don't want to use the SSCCE repository, you can also post a MINIMAL, SELF-CONTAINED code that reproduces the issue. It must be runnable by simply copying and pasting into an isolated JS file, except possibly for the database connection configuration.
Check http://sscce.org/ or https://stackoverflow.com/help/minimal-reproducible-example to learn more about SSCCE/MCVE/reprex.
Instead of using that repository, you can also clone the Sequelize repository and overwrite the `sscce.js` file in the root folder, run it locally and then provide the code here:
-->
```js
// You can delete this code block if you have included a link to your SSCCE above!
// MINIMAL, SELF-CONTAINED code here (SSCCE/MCVE/reprex)
const { createSequelizeInstance } = require('./dev/sscce-helpers');
const { Model, DataTypes } = require('.');
const sequelize = createSequelizeInstance({ benchmark: true });
class User extends Model {}
User.init({
username: DataTypes.STRING,
birthday: DataTypes.DATE
}, { sequelize, modelName: 'user' });
(async () => {
await sequelize.sync({ force: true });
const jane = await User.create({
username: 'janedoe',
birthday: new Date(1980, 6, 20)
});
console.log('\nJane:', jane.toJSON());
await sequelize.close();
})();
```
### What do you expect to happen?
......@@ -54,16 +79,15 @@ Output here
### Additional context
Add any other context or screenshots about the feature request here.
Add any other context and details here.
### Environment
- Sequelize version: XXX <!-- run `npm list sequelize` to obtain this -->
- Node.js version: XXX <!-- run `node -v` to obtain this -->
- Operating System: XXX
- If TypeScript related: TypeScript version: XXX
- If TypeScript related: TypeScript version: XXX <!-- run `npm list typescript` to obtain this -->
## Issue Template Checklist
## Bug Report Checklist
<!-- Please answer the questions below. If you don't, your issue may be closed. -->
......
.github/ISSUE_TEMPLATE/documentational-issue.md → .github/ISSUE_TEMPLATE/docs_issue.md
......@@ -10,9 +10,13 @@ assignees: ''
<!--
If you don't follow the issue template, your issue may be closed.
Please note this is an issue tracker, not a support forum.
For general questions, please use StackOverflow or Slack.
For general questions, please use StackOverflow.
-->
## Issue Creation Checklist
[ ] I have read the [contribution guidelines](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.md)
## Issue Description
### What was unclear/insufficient/not covered in the documentation
......@@ -24,23 +28,5 @@ Write here.
Write here.
### Additional context
Add any other context or screenshots about the issue here.
## Issue Template Checklist
<!-- Please answer the questions below. If you don't, your issue may be closed. -->
### Is this issue dialect-specific?
- [ ] No. This issue is relevant to Sequelize as a whole.
- [ ] Yes. This issue only applies to the following dialect(s): XXX, YYY, ZZZ
- [ ] I don't know.
### Would you be willing to resolve this issue by submitting a Pull Request?
<!-- Remember that first contributors are welcome! -->
- [ ] Yes, I have the time and I know how to start.
- [ ] Yes, I have the time but I don't know how to start, I would need guidance.
- [ ] No, I don't have the time, although I believe I could do it if I had the time...
- [ ] No, I don't have the time and I wouldn't even know how to start.
Add any other context or screenshots about the issue here.
.github/ISSUE_TEMPLATE/feature_request.md
......@@ -10,14 +10,18 @@ assignees: ''
<!--
If you don't follow the issue template, your issue may be closed.
Please note this is an issue tracker, not a support forum.
For general questions, please use StackOverflow or Slack.
For general questions, please use StackOverflow.
-->
## Issue Creation Checklist
[ ] I have read the [contribution guidelines](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.md)
## Feature Description
### Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Example: I'm always frustrated when [...]
A clear and concise description of what the problem is. Example: I'm always frustrated when ...
### Describe the solution you'd like
......@@ -45,8 +49,8 @@ Add any other context or screenshots about the feature request here.
### Is this feature dialect-specific?
- [ ] No. This issue is relevant to Sequelize as a whole.
- [ ] Yes. This issue only applies to the following dialect(s): XXX, YYY, ZZZ
- [ ] No. This feature is relevant to Sequelize as a whole.
- [ ] Yes. This feature only applies to the following dialect(s): XXX, YYY, ZZZ
### Would you be willing to implement this feature by submitting a Pull Request?
......
.github/ISSUE_TEMPLATE/other_issue.md
......@@ -10,9 +10,13 @@ assignees: ''
<!--
If you don't follow the issue template, your issue may be closed.
Please note this is an issue tracker, not a support forum.
For general questions, please use StackOverflow or Slack.
For general questions, please use StackOverflow.
-->
## Issue Creation Checklist
[ ] I have read the [contribution guidelines](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.md)
## Issue Description
A clear and concise description of what is this issue about.
......@@ -23,11 +27,8 @@ If applicable, you can add some code. In this case, an SSCCE/MCVE/reprex is much
Check http://sscce.org/ or https://stackoverflow.com/help/minimal-reproducible-example to learn more about SSCCE/MCVE/reprex.
-->
### StackOverflow / Slack attempts
If you have tried asking on StackOverflow / Slack about this, add a link to that here.
### Additional context
Add any other context or screenshots about the issue here.
## Issue Template Checklist
......
CONTRIBUTING.md
_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](https://sequelize.slack.com) & [StackOverflow](https://stackoverflow.com/questions/tagged/sequelize.js).
# Introduction
# Issues
We are happy to see that you might be interested in contributing to Sequelize! There is no need to ask for permission to contribute. For example, anyone can open issues and propose changes to the source code (via Pull Requests). Here are some ways people can contribute:
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:
* Opening well-written bug reports (via [New Issue](https://github.com/sequelize/sequelize/issues/new/choose))
* Opening well-written feature requests (via [New Issue](https://github.com/sequelize/sequelize/issues/new/choose))
* Proposing improvements to the documentation (via [New Issue](https://github.com/sequelize/sequelize/issues/new/choose))
* Opening Pull Requests to fix bugs or make other improvements
* Reviewing (i.e. commenting on) open Pull Requests, to help their creators improve it if needed and allow maintainers to take less time looking into them
* Helping to clarify issues opened by others, commenting and asking for clarification
* Answering [questions tagged with `sequelize.js` on StackOverflow](https://stackoverflow.com/questions/tagged/sequelize.js)
* Helping people in our [public Slack channel](https://sequelize.slack.com/) (note: if you don't have access, get yourself an invite automatically via [this link](http://sequelize-slack.herokuapp.com/))
### Tell us:
Sequelize is strongly moved by contributions from people like you. All maintainers also work on their free time here.
- 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?
## Opening Issues
When you post code, please use [Github flavored markdown](https://help.github.com/articles/github-flavored-markdown), in order to get proper syntax highlighting!
Issues are always very welcome - after all, they are a big part of making Sequelize better. An issue usually describes a bug, feature request, or documentation improvement request.
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.
If you open an issue, try to be as clear as possible. Don't assume that the maintainers will immediately understand the problem. Write your issue in a way that new contributors can also help (add links to helpful resources when applicable).
# Pull requests
Make sure you know what is an [SSCCE](http://sscce.org/)/[MCVE](https://stackoverflow.com/help/minimal-reproducible-example).
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:
Learn to use [GitHub flavored markdown](https://help.github.com/articles/github-flavored-markdown) to write an issue that is nice to read.
- 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](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.md#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 [async/await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) in all new tests. Specifically this means:
- don't use `EventEmitter`, `QueryChainer` or the `success`, `done` and `error` events
- don't use a done callback in your test, just return the promise chain.
- Small bugfixes and direct backports to the 4.x 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](http://usejsdoc.org/about-getting-started.html) comments. See [section 4a](#4a-check-the-documentation) for the specifics.
### Opening an issue to report a bug
Interested? Coolio! Here is how to get started:
It is essential that you provide an [SSCCE](http://sscce.org/)/[MCVE](https://stackoverflow.com/help/minimal-reproducible-example) for your issue. You can use the [papb/sequelize-sscce](https://github.com/papb/sequelize-sscce) repository. Tell us what is the actual (incorrect) behavior and what should have happened (do not expect the maintainers to know what should happen!). Make sure you checked the bug persists in the latest Sequelize version.
### 1. Prepare your environment
If you can even provide a Pull Request with a failing test (unit test or integration test), that is great! The bug will likely be fixed much faster in this case.
Here comes a little surprise: You need [Node.JS](http://nodejs.org).
### Opening an issue to request a new feature
### 2. Install the dependencies
We're more than happy to accept feature requests! Before we get into how you can bring these to our attention, let's talk about our process for evaluating feature requests:
Just "cd" into sequelize directory and run `npm ci`, see an example below:
- A feature request can have three states - *approved*, *pending* and *rejected*.
- *Approved* feature requests are accepted by maintainers as a valuable addition to Sequelize, and are ready to be worked on by anyone.
- *Rejected* feature requests were considered not applicable to be a part of the Sequelize ORM. This can change, so feel free to comment on a rejected feature request providing a good reasoning and clarification on why it should be reconsidered.
- *Pending* feature requests are waiting to be looked at by maintainers. They may or may not need clarification. Contributors can still submit pull requests implementing a pending feature request, if they want, at their own risk of having the feature request rejected (and the pull request closed without being merged).
```sh
$ cd path/to/sequelize
$ npm ci
$ npm run tsc
```
### 3. Database
Please be sure to communicate the following:
Database instances for testing can be started using Docker or you can use local instances of MySQL and PostgreSQL.
1. What problem your feature request aims to solve OR what aspect of the Sequelize workflow it aims to improve.
#### 3.a Local instances
2. Under what conditions are you anticipating this feature to be most beneficial?
For MySQL and PostgreSQL you'll need to create a DB called `sequelize_test`.
For MySQL this would look like this:
3. Why does it make sense that Sequelize should integrate this feature?
```sh
$ echo "CREATE DATABASE sequelize_test;" | mysql -uroot
```
4. See our [Feature Request template](https://github.com/sequelize/sequelize/blob/main/.github/ISSUE_TEMPLATE/feature_request.md) for more details on what to include. Please be sure to follow this template.
**HINT:** 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`.
If we don't approve your feature request, we'll provide you with our reasoning before closing it out. Some common reasons for denial may include (but are not limited to):
For Postgres, creating the database and (optionally) adding the test user this would look like:
- Something too similar to already exists within Sequelize
- This feature seems out of scope of what Sequelize exists to accomplish
```sh
$ psql
We don't want to deny feature requests that could potentially make our users lives easier, so please be sure to clearly communicate your goals within your request!
# create database sequelize_test;
# create user postgres with superuser; -- optional; usually built-in
```
### Opening an issue to request improvements to the documentation
You may need to specify credentials using the environment variables `SEQ_PG_USER` and `SEQ_PG_PW` when running tests or set a password of 'postgres' for the postgres user on your local database to allow sequelize to connect via TCP to localhost. Refer to `test/config/config.js` for the default credentials and environment variables.
Please state clearly what is missing/unclear/confusing in the documentation. If you have a rough idea of what should be written, please provide a suggestion within the issue.
For Postgres you may also need to install the `postgresql-postgis` package (an optional component of some Postgres distributions, e.g. Ubuntu). The package will be named something like: `postgresql-<pg_version_number>-postgis-<postgis_version_number>`, e.g. `postgresql-9.5-postgis-2.2`. You should be able to find the exact package name on a Debian/Ubuntu system by running the command: `apt-cache search -- -postgis`.
## Opening a Pull Request
Create the following extensions in the test database:
A Pull Request is a request for maintainers to "pull" a specific change in code (or documentation) from your copy ("fork") into the repository.
```
CREATE EXTENSION postgis;
CREATE EXTENSION hstore;
CREATE EXTENSION btree_gist;
CREATE EXTENSION citext;
```
Anyone can open a Pull Request, there is no need to ask for permission. Maintainers will look at your pull request and tell you if anything else must be done before it can be merged.
#### 3.b Docker
The target of the Pull Request should be the `main` branch (or in rare cases the `v5` branch, if previously agreed with a maintainer).
Make sure `docker` and `docker-compose` are installed.
Please check the *allow edits from maintainers* box when opening it. Thank you in advance for any pull requests that you open!
If running on macOS, install [Docker for Mac](https://docs.docker.com/docker-for-mac/).
If you started to work on something but didn't finish it yet, you can open a draft pull request if you want (by choosing the "draft" option). Maintainers will know that it's not ready to be reviewed yet.
Now launch the docker mysql and postgres servers with this command (you can add `-d` to run them in daemon mode):
A pull request should mention in its description one or more issues that is addresses. If your pull request does not address any existing issue, explain in its description what it is doing - you are also welcome to write an issue first, and then mention this new issue in the PR description.
```sh
$ docker-compose up postgres-95 mysql-57 mssql
```
If your pull request implements a new feature, it's better if the feature was already explicitly approved by a maintainer, otherwise you are taking the risk of having the feature request rejected later and your pull request closed without merge.
> **_NOTE:_** If you get the following output:
>
> ```
> ...
> Creating mysql-57 ... error
>
> ERROR: for mysql-57 Cannot create container for service mysql-57: b'create .: volume name is too short, names should be at least two alphanumeric characters'
>
> ERROR: for mysql-57 Cannot create container for service mysql-57: b'create .: volume name is too short, names should be at least two alphanumeric characters'
> ERROR: Encountered errors while bringing up the project.
> ```
>
> You need to set the variables `MARIADB_ENTRYPOINT` and `MYSQLDB_ENTRYPOINT` accordingly:
>
> ```sh
> $ export MARIADB_ENTRYPOINT="$PATH_TO_PROJECT/test/config/mariadb"
> $ export MYSQLDB_ENTRYPOINT="$PATH_TO_PROJECT/test/config/mysql"
> ```
**MSSQL:** Please run `npm run setup-mssql` to create the test database.
**POSTGRES:** Sequelize uses [special](https://github.com/sushantdhiman/sequelize-postgres) Docker image for PostgreSQL, which install all the extensions required by tests.
Once you open a pull request, our automated checks will run (they take a few minutes). Make sure they are all passing. If they're not, make new commits to your branch fixing that, and the pull request will pick them up automatically and rerun our automated checks.
### 4. Running tests
Note: if you believe a test failed but is completely unrelated to your changes, it could be a rare situation of a *flaky test* that is not your fault, and if it's indeed the case, and everything else passed, a maintainer will ignore the *flaky test* and merge your pull request, so don't worry.
A pull request that fixes a bug or implements a new feature must add at least one automated test that:
- Passes
- Would not pass if executed without your implementation
## How to prepare a development environment for Sequelize
### 0. Requirements
Most operating systems provide all the needed tools (including Windows, Linux and MacOS):
* Mandatory:
* [Node.js](http://nodejs.org)
* [Git](https://git-scm.com/)
* Optional (recommended):
* [Docker](https://docs.docker.com/get-docker/)
* It is not mandatory because you can easily locally run tests against SQLite without it.
* It is practically mandatory if you want to locally run tests against any other database engine (MySQL, MariaDB, Postgres and MSSQL), unless you happen to have the engine installed and is willing to make some manual configuration.
* [Visual Studio Code](https://code.visualstudio.com/)
* [EditorConfig extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
* Also run `npm install --global editorconfig` to make sure this extension will work properly
* [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
### 1. Clone the repository
Clone the repository (if you haven't already) via `git clone https://github.com/sequelize/sequelize`. If you plan on submitting a pull request, you can create a fork by clicking the *fork* button and clone it instead with `git clone https://github.com/your-github-username/sequelize`, or add your fork as an upstream on the already cloned repo with `git remote add upstream https://github.com/your-github-username/sequelize`.
### 2. Install the Node.js dependencies
Run `npm install` (or `yarn install`) within the cloned repository folder.
### 3. Prepare local databases to run tests
If you're happy to run tests only against an SQLite database, you can skip this section.
All tests are located in the `test` folder (which contains the
lovely [Mocha](https://mochajs.org/) tests).
#### 3a. With Docker (recommended)
```sh
$ npm run test-all || test-mysql || test-sqlite || test-mssql || test-postgres || test-postgres-native
If you have Docker installed, use any of the following commands to start fresh local databases of the dialect of your choice:
$ # alternatively you can pass database credentials with $variables when testing
$ DIALECT=dialect SEQ_DB=database SEQ_USER=user SEQ_PW=password npm test
* `npm run setup-mariadb`
* `npm run setup-mysql`
* `npm run setup-postgres`
* `npm run setup-mssql`
*Note:* if you're using Windows, make sure you run these from Git Bash (or another MinGW environment), since these commands will execute bash scripts. Recall that [it's very easy to include Git Bash as your default integrated terminal on Visual Studio Code](https://code.visualstudio.com/docs/editor/integrated-terminal).
Each of these commands will start a Docker container with the corresponding database, ready to run Sequelize tests.
##### Hint for Postgres
You can also easily start a local [pgadmin4](https://www.pgadmin.org/docs/pgadmin4/latest/) instance at `localhost:8888` to inspect the contents of the test Postgres database as follows:
```
docker run -d --name pgadmin4 -p 8888:80 -e 'PGADMIN_DEFAULT_EMAIL=test@example.com' -e 'PGADMIN_DEFAULT_PASSWORD=sequelize_test' dpage/pgadmin4
```
For docker users you can use these commands instead
#### 3b. Without Docker
You will have to manually install and configure each of database engines you want. Check the `dev/dialect-name` folder within this repository and look carefully at how it is defined via Docker and via the auxiliary bash script, and mimic that exactly (except for the database name, username, password, host and port, that you can customize via the `SEQ_DB`, `SEQ_USER`, `SEQ_PW`, `SEQ_HOST` and `SEQ_PORT` environment variables, respectively).
### 4. Running tests
```sh
$ DIALECT=mysql npm run test-docker # Or DIALECT=postgres for Postgres SQL
Before starting any work, try to run the tests locally in order to be sure your setup is fine. Start by running the SQLite tests:
# Only integration tests
$ DIALECT=mysql npm run test-docker-integration
```
npm run test-sqlite
```
Then, if you want to run tests for another dialect, assuming you've set it up as written on section 3, run the corresponding command:
* `npm run test-mysql`
* `npm run test-mariadb`
* `npm run test-postgres`
* `npm run test-mssql`
There are also the `test-unit-*` and `test-integration-*` sets of npm scripts (for example, `test-integration-postgres`).
### 5. Commit
### 5. Commit your modifications
Sequelize follows the [AngularJS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.em2hiij8p46d). The allowed categories are `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test` and `meta`.
Sequelize follows the [AngularJS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.em2hiij8p46d).
Example:
feat(pencil): add 'graphiteWidth' option
```
feat(pencil): add `graphiteWidth` option
```
Commit messages are used to automatically generate a changelog. They will be validated automatically using [commitlint](https://github.com/marionebl/commitlint)
Commit messages are used to automatically generate a changelog and calculate the next version number according to [semver](https://semver.org/). They will be validated automatically using [commitlint](https://github.com/marionebl/commitlint).
Then push and send your pull request. Happy hacking and thank you for contributing.
......@@ -158,13 +187,3 @@ Have a look at our [.eslintrc.json](https://github.com/sequelize/sequelize/blob/
# Contributing to the documentation
For contribution guidelines for the documentation, see [CONTRIBUTING.DOCS.md](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.DOCS.md).
# Publishing a release (For Maintainers)
1. Ensure that latest build on the main branch is green
2. Ensure your local code is up to date (`git pull origin main`)
3. `npm version patch|minor|major` (see [Semantic Versioning](http://semver.org))
4. Update changelog to match version number, commit changelog
5. `git push --tags origin main`
6. `npm publish .`
7. Copy changelog for version to release notes for version on github
README.md
......@@ -13,6 +13,8 @@ Sequelize follows [Semantic Versioning](http://semver.org) and supports Node v10
New to Sequelize? Take a look at the [Tutorials and Guides](https://sequelize.org/master). You might also be interested in the [API Reference](https://sequelize.org/master/identifiers).
Would you like to contribute? Read [our contribution guidelines](https://github.com/sequelize/sequelize/blob/main/CONTRIBUTING.md) to know more. There are many ways to help.
### v6 Release
You can find the detailed changelog [here](https://github.com/sequelize/sequelize/blob/main/docs/manual/other-topics/upgrade-to-v6.md).
......
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!