Hi! We're really excited that you are interested in contributing to Vue-Admin. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:
- Code of Conduct
- Issue Reporting Guidelines
- Pull Request Guidelines
- Development Setup
- Project Structure
-
The
master
branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against themaster
branch. -
Checkout a topic branch from the relevant branch, e.g.
develop
, and merge back against that branch. Please follow this convention for the new branch:issueNumber-githubUsernaame-commitTitle
. -
Most of the contributed work should generally target the
src
folder. -
It's OK to have multiple small commits as you work on the PR - We may squash them before merging if necessary.
-
Make sure
npm run test
passes. (see development setup) -
If adding a new feature:
- Add accompanying test case (at the moment a unit test would be enough).
- Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first and have it approved before working on it.
-
If fixing bug:
- If you are resolving a special issue, please follow the branch naming convention mentioned above.
- Provide a detailed description of the bug in the PR. Live demo preferred.
- Add appropriate test coverage if applicable.
You will need Node.js version 8+.
After cloning the forked repository, run:
npm install
We don't expect any strict convention, but we'd be grateful if you summarize what your modifications content is about when writing a commit.
# watch and auto re-build the local instance
npm run serve
# run unit tests
npm run test:unit
# run e2e tests using Cypress
npm run test:e2e
# run linting checking
npm run lint
# build all dist files
npm run build
# run the full test suite, including linting checking
npm run test
There are some other scripts available in the scripts
section of the package.json
file.
The default test script will do the following: lint with ESLint, unit tests with coverage and e2e tests. Please make sure to have this pass successfully before submitting a PR. Although the same tests will be run against your PR on the CI server, it is better to have it working locally.
-
dist
: contains built files for distribution. Note this directory is only updated when a release happens; they do not reflect the latest changes in development branches. -
test
: contains all tests. The unit tests are written with Jest and run using @vue/cli-plugin-unit-jest. The e2e tests are written with Cypress. -
src
: contains the source code. The codebase is written in ES2015. -
components
: contains single file components (*.vue
files).This components responsibilities are of wide variety. There are core components such as
Admin
,Resource
, and their composers, the main layout:AppLayout
and theCore
composer. The rest of thesrc
components play a significant role, however they can entirely replaceable by customized views: Actions such asCreate
,Show
,Edit
,List
; layouts:AuthLayout
,HomeLayout
,UnauthorizedLayout
.Note: this structure may change in the future
-
constants
: contains static values usually helpful to assign dom references and re-use content between the source code and test code. -
router
: contains router related operationsThe router module relies heavily on the
vue-router
API for adding routes and applying the navigation guards. -
store
: contains code related to the vuex modules.This set of modules currently play an important role in the application interaction.
alerts
: manages the snackbar and notifications systemcrud
: creates and manages the resources modules using vuex-crudentities
: related to form data managementrequests
: related to ui/ux side-effects managementresources
: related to resources routes management
-
va-auth
: contains code related to the authentication and authorization interaction.It's just a vuex module that handles authentication and authorization actions and mantains it's state. This module exports the auth types to perform any user operation to the Vue-Admin auth system.
-
validators
: contains code related to schema validation.
This Contributing Guidelines were adapted from the Vue.js Contributing Guide.