This guide covers ways in which you can become a part of the ongoing development of Quasar.
But, before we begin, a first important note. Everyone interacting in Quasar is expected to follow the Quasar code of conduct.
Now that we’ve got that covered, let’s go!
After reading this guide, you will know:
- How to use GitHub to report issues.
- How to clone master and run the test suite.
- How to help resolve existing issues.
- How to contribute to the Quasar documentation.
- How to create a Quasar App Extension.
- How to contribute to the Quasar code.
Quasar is not “someone else’s framework”. Many people have contributed to Quasar ranging from a single character to massive architectural changes or significant documentation - all with the goal of making Quasar better for everyone. Even if you don’t feel up to writing code or documentation yet, there are a variety of other ways that you can contribute, from reporting issues to testing patches.
Help with Support
One of the easiest ways to contribute is to answer questions in the different Q&A systems we have. Be a supportive and positive member of the Quasar community by answering questions you know answers to, or even by adding your best guess. Being a part of such discussions can also be a good learning experience. It’s a win-win!
Here are our discussion/Q&A venues:
- Forum: The best place to ask questions and get answers about Quasar and its ecosystem.
- Chat: A place for Quasar devs to meet and chat in real time.
Share (and Build) Your Experience
Apart from answering questions and sharing resources in the forum and chat, there are a few other less obvious ways to share and expand what you know:
- Develop learning materials. It’s often said that the best way to learn is to teach. If there’s something interesting you’re doing with Quasar, strengthen your expertise by writing a blog post, developing a workshop, or even publishing a gist that you share on social media.
- Share your tech stack. Show others which technologies are well tested and can be integrated with Quasar. Promote your project and fill out your favorite Quasar-based stack. Make sure to mention @Quasarframework and all other relevant technologies.
- Watch a repo you care about. This will send you notifications whenever there’s activity in that repository, giving you insider knowledge about ongoing discussions and upcoming features. It’s a fantastic way to build expertise so that you’re eventually able to help address issues and pull requests.
Reporting an Issue
- GitHub: If you have a bug to report or feature to request, that’s what the GitHub issues are for.
Reporting a vulnerability
Please do not report security vulnerabilities with public GitHub issue reports. Follow the Report a vulnerability steps for security issues.
If you’ve found a problem in Quasar which is not a security risk, do a search on GitHub under Issues to check if it is already answered or even fixed in the development branch (
The issue list of the main repo is exclusively for bug reports and feature requests. Non-conforming issues will be closed immediately.
Check if the issue is reproducible with the latest stable version of Quasar. If you are using a pre-release, please indicate the specific version you are using.
It is required that you clearly describe the steps necessary to reproduce the issue you are running into. Although we would love to help our users as much as possible, diagnosing issues without clear reproduction steps is extremely time-consuming and simply not sustainable.
Use only the minimum amount of code necessary to reproduce the unexpected behavior. A good bug report should isolate specific methods that exhibit unexpected behavior and precisely define how expectations were violated. What did you expect the method or methods to do, and how did the observed behavior differ? The more precisely you isolate the issue, the faster we can investigate.
Issues with no clear reproduction steps will not be triaged. If an issue labeled “need repro” receives no further input from the issue author for more than 5 days, it will be closed.
If your issue is resolved but still open, don’t hesitate to close it. In case you found a solution by yourself, it could be helpful to explain how you fixed it.
Most importantly, we beg your patience: the team must balance your request against many other responsibilities — fixing other bugs, answering other questions, new features, new documentation, etc. The issue list is not paid support and we cannot make guarantees about how fast your issue can be resolved, although we do our very best.
Helping to Resolve Existing Issues
As a next step beyond reporting issues, you can help the Quasar Team resolve existing ones by providing feedback about them. If you are new to Quasar development, that might be a great way to walk your first steps, you’ll get familiar with the code base and the processes.
If you check the issues list in GitHub Issues, you’ll find lots of issues already requiring attention. What can you do for these? Quite a bit, actually:
Verifying Bug Reports
For starters, it helps just to verify bug reports. Can you reproduce the reported issue on your own computer? If so, you can add a comment to the issue saying that you’re seeing the same thing.
If an issue is very vague, can you help narrow it down to something more specific? Maybe you can provide additional information to help reproduce a bug, or help by eliminating needless steps that aren’t required to demonstrate the problem.
Anything you can do to make bug reports more succinct or easier to reproduce helps folks trying to write code to fix those bugs - whether you end up writing the code yourself or not.
You can also help out by examining pull requests that have been submitted to Quasar via GitHub. In order to apply someone’s changes, you need to first create a dedicated branch:
$ git checkout -b testing_branch
Then, you can use their remote branch to update your codebase. For example, let’s say the GitHub user JohnSmith has forked and pushed to a topic branch “orange” located at https://github.com/JohnSmith/quasar.
$ git remote add JohnSmith https://github.com/JohnSmith/quasar.git $ git pull JohnSmith orange
After applying their branch, test it out! Here are some things to think about:
- Does the change actually work?
- Does it have the proper documentation coverage? Should documentation elsewhere be updated?
- Do you like the implementation? Can you think of a nicer or faster way to implement a part of their change?
Once you’re happy that the pull request contains a good change, comment on the GitHub issue indicating your approval. Your comment should indicate that you like the change and what you like about it. Something like:
Example pull request comment
I like the way you’ve restructured the code in card.vue - much nicer. Documentation is updated too.
If your comment simply reads “+1”, then odds are that other reviewers aren’t going to take it too seriously. Show that you took the time to review the pull request.
Contributing to the Quasar Documentation
You can help improve the Quasar documentation by making it more coherent, consistent, or readable, adding missing information, correcting factual errors, fixing typos, or bringing them up to date with the latest edge Quasar.
Typos or small changes can be fixed directly from the documentation
Use a pencil icon in the top right corner of every documentation page. Edit the source file, preview the changes, add a description of your change and hit
Propose a file change and on the next screen
Create pull request.
For larger edits change the Quasar source files (located here on GitHub).
Documentation Best Practices
Over time we consolidated a set of rules which we follow and following them will speed up the merge process:
- Capitalize titles, see How to Use Capitalize My Title.
- Use the present tense.
- Be concise, avoid text / code duplication.
- Link to the external sources which are used as master information sources and are usually updated more frequently, like Mozilla MDN, Vue.js API rather than compiled tutorials which tend to be outdated soon.
- Do the proofreading before opening a PR
- Do not repeat texts from other sources, but keep only things which are relevant and shows in a context Quasar specific features
- Use official names. For example use
- Exclude from PR all drafts and unfinished pages
Navigate to the Quasar GitHub repository and press “Fork” in the upper right-hand corner.
Select v1 branch
Make sure you have
v1 branch selected and this is where all the work is done.
Clone the forked repository
To be able to change the documentation, you need to clone forked repository:
$ git clone https://github.com/your-user-name/quasar.git
Install the required dependencies.
$ cd quasar/docs $ yarn # or npm install
Running documentation against your local repository
$ quasar dev # or quasar dev -m ssr
The documentation runs against your local cloned repository.
Edit and test your changes locally
Commit your changes
When you’re happy with the change on your computer, you need to commit the changes to Git:
$ git commit -a
This should fire up your editor to write a commit message. When you have finished, save and close to continue.
Update your local repository
It’s pretty likely that other changes to master have happened while you were working. Go get them.
- Add a remote Quasar repository as an upstream
$ git remote add upstream https://github.com/quasarframework/quasar.git
- Check out your fork’s local
$ git checkout v1 > Switched to branch 'v1'
- Merge the changes from
upstream/v1into your local
v1branch. This brings your fork’s
v1branch into sync with the upstream repository, without losing your local changes.
$ git merge upstream/dev
No conflicts? Tests still pass? Change still seems reasonable to you? Then move on and open a pull request to apply your changes to the dev branch in main Quasar repository.
Issue a pull request
Navigate to your repository you just pushed to (e.g. https://github.com/your-user-name/quasar) and click on “New Pull Request” seen in the left top panel.
Ensure the change sets you introduced are included. Fill in some details about your potential patch including a meaningful title. When finished, press Click on “Create pull request”. The Quasar core team will be notified about your submission.
Write your Story
We’re always looking for great write-ups on how you are using Quasar or the great experiences you’ve had with Quasar. If you write an article, we will publish it on our Medium publication channel and we’ll also make sure your article gets the attention it deserves with our social media presence. If you are interested, please contact blog(at)quasar.dev. We’d love to hear from you!
Create new Quasar App Extension
An easy way to start to contribute to Quasar is to generalize the code you have created on your project and publish it as a Quasar App Extension. Follow this guide on how to create a new extension.
Contributing to the Quasar UI Source Code
As with any project, there are rules to contributing. Ours are written here, please read them carefully. After that, read the Quasar code of conduct and you’ll be ready to contribute to Quasar’s core repositories.
An article Look at the source code will help you to get familiar with a Quasar code base.
Pull Request Guidelines
Checkout a topic branch from the relevant branch, e.g.
v1, and merge back against that branch.
DO NOT check in
distin the commits.
It’s OK to have multiple small commits as you work on the PR - we will let GitHub automatically squash it before merging.
If adding new feature:
- Provide convincing reason to add this feature. Ideally you should open a suggestion issue first and have it greenlighted before working on it.
If fixing a bug:
- If you are resolving a special issue, add
(fix: #xxxx[,#xxx])(#xxxx is the issue id) in your PR title for a better release log, e.g.
fix: update entities encoding/decoding (fix #3899).
- Provide detailed description of the bug in the PR. Live demo preferred.
- If you are resolving a special issue, add
After cloning the repo run:
$ cd ui $ yarn # or: npm install
Commonly used NPM scripts
# Start dev server with a demo app. This app has Quasar source code linked directly so any change will trigger HMR (Hot Module Reload) on the dev server. # There's a section for each feature where tests are made. $ yarn dev # or: npm run dev # build all dist files, including npm packages $ yarn build # or: npm run build # build only js dist files $ yarn build js # or: npm run build js # build only css dist files $ yarn build css # or: npm run build css # lint sources $ yarn lint # or: npm run lint
Project Structure (/ui)
build- contains build-related configuration files. In most cases you don’t need to touch them.
src- contains the source code, obviously. The codebase is written in ES2015.
components- JS, Stylus and JSON (API) files for Quasar Vue components
directives- Vue directives supplied by Quasar
plugins- Quasar plugins
css- Stylus definitions and core code for Quasar themes
mixins- code for global mixins that are internal to Quasar
utils- utilities used by the framework and exported to the public API
ie-compat- code for IE11 compatibility
lang- Quasar language packs
icon-set- Quasar icon sets
dist- contains built files for distribution (only after a build). Note this directory is only updated when a release happens; they do not reflect the latest changes in development branches.
dev- app with Quasar sources linked directly used for testing purposes. Each feature/component has its own
*.vuefile. Adding a new file automatically creates a route for it and adds it to the “homepage” list (based on the file name).
Dev Server for Quasar (/ui)
yarn dev (or
npm run dev) starts up a dev server which uses HMR (Hot Module Reload) for Quasar source code. You can easily test your changes by making necessary changes to
Thank you to all the people who already contributed to Quasar!