Skip to content

Commit 72aaa08

Browse files
valasekrstoenescu
valasek
authored and
rstoenescu
committed
docs[docs]: New sections in the contribution guide - starting and run… (quasarframework#5137)
* docs[docs]: New sections in the contribution guide - starting and running projects, maintainers and commit rules * Update commit-conventions.md * Update running-projects.md
1 parent db2a845 commit 72aaa08

File tree

7 files changed

+264
-6
lines changed

7 files changed

+264
-6
lines changed

‎docs/src/assets/menu.js‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,30 @@
1+
const contributionGuide = [
2+
{
3+
name: 'Contribution Guide',
4+
path: 'contribution-guide'
5+
},
6+
{
7+
name: 'Running Projects',
8+
path: 'running-projects',
9+
badge: 'new'
10+
},
11+
{
12+
name: 'Start a New Project',
13+
path: 'new-project',
14+
badge: 'new'
15+
},
16+
{
17+
name: 'Project Maintainer Role',
18+
path: 'project-maintainer',
19+
badge: 'new'
20+
},
21+
{
22+
name: 'Commit Conventions',
23+
path: 'commit-conventions',
24+
badge: 'new'
25+
}
26+
]
27+
128
const gettingStarted = [
229
{
330
name: 'Pick Quasar Flavour',
@@ -38,11 +65,6 @@ const gettingStarted = [
3865
name: 'Roadmap',
3966
path: 'roadmap'
4067
},
41-
{
42-
name: 'Contribution Guide',
43-
badge: 'new',
44-
path: 'contribution-guide'
45-
},
4668
{
4769
name: 'Upgrade guide',
4870
path: 'upgrade-guide'
@@ -1021,6 +1043,12 @@ module.exports = [
10211043
icon: 'people',
10221044
path: 'meet-the-team'
10231045
},
1046+
{
1047+
name: 'Contribution Guide',
1048+
icon: 'code',
1049+
path: 'contribution-guide',
1050+
children: contributionGuide
1051+
},
10241052
{
10251053
name: 'Getting Started',
10261054
icon: 'flight_takeoff',

‎docs/src/pages/contribution-guide/commit-conventions.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Commit Conventions
3+
desc: Play with Quasar on a jsFiddle, Codepen or Codesandbox templates.
4+
---
5+
6+
## Goals
7+
- Allow ignoring commits by git bisect (not important commits like formatting)
8+
- Provide better information when browsing the history
9+
10+
:::warning
11+
This rule applies to ALL [Quasar repositories](https://github.com/quasarframework).
12+
:::
13+
14+
Well-cared log is a beautiful and useful thing. `git blame`, `revert`, `rebase`, `log`, `shortlog` and other subcommands come to life. Reviewing others’ commits and pull requests becomes something worth doing, and suddenly can be done independently. Understanding why something happened months or years ago becomes not only possible but efficient.
15+
16+
## The Rules of a Great Git Commit Message
17+
18+
1. Separate subject from body with a blank line
19+
2. Limit the subject line to 70 characters
20+
3. Capitalize the subject line
21+
4. Do not end the subject line with a period
22+
5. Use the imperative mood in the subject line
23+
6. Wrap the body at 80 characters
24+
7. Use the body to explain what and why vs. how
25+
26+
## Format of a Commit Message
27+
28+
```
29+
type(<scope>): <Subject> #<github-ref-id>
30+
31+
<body>
32+
33+
<footer>
34+
```
35+
36+
### Example of a Commit Message
37+
38+
```
39+
fix(ui): Ensure Range headers adhere more closely to RFC 2616 #2310
40+
41+
To add new dependency use `range-parser`to compute the range.
42+
It is more well-tested in the wild.
43+
44+
BREAKING CHANGE:
45+
port-runner command line option has changed to runner-port.
46+
To migrate your project, change all the commands,
47+
where you use --port-runner to --runner-port.
48+
```
49+
50+
## Message Subject (First Line)
51+
52+
The first line cannot be longer than 70 characters, the second line is always blank. The type and scope should always be lowercase as shown below.
53+
54+
**Allowed `<type>` values:**
55+
56+
- **feat** - new feature for the user, not a new feature for build script
57+
- **fix** - bug fix for the user, not a fix to a build script
58+
- **docs** - documentation only changes
59+
- **style** - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
60+
- **refactor** - refactoring production code, a code change that neither fixes a bug nor adds a feature
61+
- **chore** - other changes that don't modify src or test files; no production code change
62+
- **perf** - change that improves performance
63+
- **revert** - reverts a previous commit
64+
- **test** - adding missing tests, refactoring tests; no production code change
65+
- **build** - changes that affect the build system or external dependencies (example scopes: gulp, npm)
66+
- **ci** - changes to our Continuous Integrations configuration files and scripts (example scopes: Travis, Circle CI)
67+
68+
**Example `<scope>` values:**
69+
70+
- ui, cli, api, touchswipe, qtime, etc.
71+
72+
:::info
73+
The `<scope>` can contain more values separated by comma. Example: `fix(ui,cli): Cordova mode added`.
74+
75+
The `<scope>` can be empty (e.g. if the change is a global), in which case the parentheses are omitted.
76+
:::
77+
78+
## Message Body
79+
80+
- uses the imperative, present tense: “change” not “changed” nor “changes”
81+
- includes motivation for the change and contrasts with previous behavior
82+
83+
## Message Footer
84+
85+
### Breaking Changes
86+
87+
All breaking changes have to be mentioned as a breaking change block in the footer, which should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then the description of the change, justification and migration notes.
88+
89+
```
90+
BREAKING CHANGE: isolate scope bindings definition has changed and
91+
the inject option for the directive controller injection was removed.
92+
93+
To migrate the code follow the example below:
94+
95+
Before:
96+
97+
scope: {
98+
myAttr: 'attribute',
99+
myBind: 'bind',
100+
myExpression: 'expression',
101+
myEval: 'evaluate',
102+
myAccessor: 'accessor'
103+
}
104+
105+
After:
106+
107+
scope: {
108+
myAttr: '@',
109+
myBind: '@',
110+
myExpression: '&',
111+
// myEval - usually not useful, but in cases where the expression is assignable, you can use '='
112+
myAccessor: '=' // in directive's template change myAccessor() to myAccessor
113+
}
114+
```
115+
116+
### Referencing Issues
117+
118+
Closed issues should be listed on a separate line in the footer prefixed with "Closes" keyword like this:
119+
120+
`Closes #234`
121+
122+
or in the case of multiple issues:
123+
124+
`Closes #123, #245, #992`
125+
126+
## Further Reading
127+
128+
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
129+
- [Karma Runner Git Commit Msg](http://karma-runner.github.io/4.0/dev/git-commit-msg.html)
130+
- [AngularJS Git Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#)
131+
- [Commit Message Conventions](https://gist.github.com/stephenparish/9941e89d80e2bc58a153)

docs/src/pages/start/contribution-guide.md renamed to docs/src/pages/contribution-guide/contribution-guide.md

File renamed without changes.

‎docs/src/pages/contribution-guide/new-project.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: How-to Start a New Project
3+
desc: Play with Quasar on a jsFiddle, Codepen or Codesandbox templates.
4+
---
5+
6+
You have a great new idea which is in line with the [Quasar vision](introduction-to-quasar). Great, here is how to make it happen!
7+
8+
1. Email to [Razvan](razvan.stoenescu@gmail.com) the following:
9+
10+
a. **The need** you are fulfilling with the new Quasar Project
11+
12+
b. **Name of the owner**/maintainer the project?
13+
14+
c. **Vision** and a **technical high-level overview**
15+
16+
d. **When do you plan the first public release**?
17+
18+
e. **Milestones** with estimated dates
19+
20+
f. How much **time you need from the Quasar team**
21+
22+
g. Document the **changes** which are needed **in the Quasar core / extensions**
23+
24+
h. Sustainability plan - any project creates more work and pressure on the existing Quasar team - what is **your long-term maintenance plan**
25+
26+
2. Set up a meeting with Razvan to discuss it and invite all engaged in the project
27+
28+
3. When agreed, add the project to the list of [running projects](contribution-guide/running-projects)

‎docs/src/pages/contribution-guide/project-maintainer.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: The Role of the Project Maintainer
3+
desc: Play with Quasar on a jsFiddle, Codepen or Codesandbox templates.
4+
---
5+
6+
## Your Profile
7+
8+
- You have a vision on something great that you want to build and own
9+
- You have enough time to put into it to succeed (although, yes, “You may have a job and the job is your priority, not this Quasar Project” --- this is perfectly fine)
10+
- You are not already involved in other projects that take a lot of your time and focus
11+
- You love open source
12+
- You want to help others
13+
- You can accept constructive criticism
14+
15+
## Your Responsibilities
16+
17+
- You are loosely aware of the entire Quasar ecosystem / inner-workings and in a detail of your Quasar feature / component / app extension / area.
18+
- You are recognized in the community (forum / chat) as the authority and lead over your Quasar feature / component / app extension / area and you actively supports it
19+
- You document, communicate and keep updated the vision of the Quasar feature / component / app extension / area that you are responsible for
20+
- You deliver the vision by implementing, fixing bugs, reviewing and merging PRs directly and via contributors
21+
- You focus on high usability for the end users - demos, documentation, community requests via forum and Discord
22+
- You provide inputs for Marketing and Media departments for articles on your Quasar Project
23+
- you don’t have to be the one writing the articles, although preferred, but at least find someone willing
24+
- You provides a code review for other Quasar maintainers and request a code review of your contributions
25+
- You keep track of the ongoing work and reported issues to make sure that it gets reviewed and merged in a timely manner.
26+
- You acknowledge every important contributor and give credit for their work (also in written form on the repo README, on every presentation material, on documentation).
27+
- You have also the final responsibility
28+
- If no reviewer can be found for an important contribution, you review.
29+
- If no developer can be found to fix an important bug, you develop.
30+
- If something goes wrong, it’s eventually your fault.
31+
- You keep the Quasar team updated at least on bi-weekly basis
32+
- You have regular calls with Razvan
33+
- You post a short project status into Discord #projects-status channel
34+
- You are brave to step down when you do not have time - it is perfectly fine to announce it.
35+
36+
More info - [Best Practices for Maintainers](https://opensource.guide/best-practices/)

‎docs/src/pages/contribution-guide/running-projects.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Active Project, Goals and Maintainers
3+
desc: Play with Quasar on a jsFiddle, Codepen or Codesandbox templates.
4+
---
5+
6+
## List of Projects with Active Maintainer
7+
8+
| Project | Responsibility | Maintainer | Repo, Links |
9+
| --- | --- | --- | --- |
10+
| Core UI, CLI | Ultimate responsibility of the Quasar, Quasar Core | Razvan | [Main repo](https://github.com/quasarframework/quasar) |
11+
| Media | Quasar is well known in JavaScript / Vue.js / backend / mobile and desktop dev community | Scott | [Facebook](https://www.facebook.com/QuasarFramework), [Medium](https://medium.com/quasar-framework), [Twitter](https://twitter.com/quasarframework) |
12+
| Procedures | Quasar is perceived as a well-managed and transparent OSS initiative with well-defined responsibilities and processes | Stanislav | [Contribution guide](contribution-guide/contribution-guide), [Internal rules](https://github.com/rstoenescu/quasar-procedures) |
13+
| BEX | Browser Extension CLI mode | Allan | [#76](https://github.com/quasarframework/quasar/issues/76)|
14+
| Capacitor | Capacitor CLI Mode | Noah | [#4388](https://github.com/quasarframework/quasar/issues/4388), [#4988](https://github.com/quasarframework/quasar/issues/4988), [CLI repo](https://github.com/quasarframework/quasar/tree/dev/cli) integration|
15+
| UI App Ext | Create and maintain UI extensions | Jeff | |
16+
| Firebase | Docs and possibly an App Ext | Adam | [repo](https://github.com/quasarframework/app-extension-firebase) |
17+
| Quasar ESLint plugin | Plugin for ESLint with Quasar upgrade support warnings | Jeff | [repo](https://github.com/quasarframework/eslint-plugin-quasar)|
18+
| Typescript | Full Typescript support for Quasar | Noah | [repo](https://github.com/quasarframework/app-extension-typescript) |
19+
| Electron mode | Maintenance and enhancements | Noah | [CLI repo](https://github.com/quasarframework/quasar/tree/dev/cli) integration |
20+
| Quasar Testing AE | Maintenance and enhancements | Noah, Adam | [repo](https://github.com/quasarframework/quasar-testing)|
21+
22+
## List of Projects Where New Maintainer is Needed
23+
These project are inevitable part of the Quasar framework but to keep on our promise "to raise the bar for web development as a whole" we are looking for an active maintainer.
24+
25+
If you are interested, read [The Role of the Project Maintainer](contribution-guide/project-maintainer) and let Razvan know via [Discord chat](https://chat.quasar.dev/).
26+
27+
We can promise you that your Javascript and Vue.js skills will reach the stars!
28+
29+
| Project | Required Skills | Links |
30+
| --- | --- | --- | --- |
31+
| Marketing | Monetization strategy and its implementation, PR, Newsletter, Articles | |
32+
| Security | Discord#security shall contain the latest security flaws | Security | [Discord chat](https://chat.quasar.dev/) Security channel|
33+
| Cordova mode | [Apache Cordova](https://cordova.apache.org/)| [What is Cordova](https://quasar.dev/quasar-cli/developing-cordova-apps/introduction),<br/> [CLI repo](https://github.com/quasarframework/quasar/tree/dev/cli) integration |
34+
| Icon Genie | JS, Vue.js, minification strategies, graphic design | [repo](https://github.com/quasarframework/app-extension-icon-genie)|
35+
| Wizard AE | JS, Vue.js | [repo](https://github.com/quasarframework/app-extension-wizard) |

‎docs/src/pages/meet-the-team.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,6 @@ components:
77

88
Hailing from all around the planet, the Quasar Team is not only international but full of people with a vast range of fields of expertise. From real rocket engineers to Fortune 500 developers, the unifying factor among us is our dedication to quality and the love for our community of contributors and developers.
99

10-
With hundreds of contributors to Quasar, **the list of people you can meet below is by no means exhaustive**. Just remember to thank everyone using Quasar and supporting us, because together we all help you push your products light-years ahead of your competition. A great way to do that is to [donate](https://donate.quasar.dev).
10+
With hundreds of contributors to Quasar, **the list of people you can meet below is by no means exhaustive**. Just remember to thank everyone using Quasar and supporting us, because together we all help you push your products light-years ahead of your competition. A great way to do that is to [donate](https://donate.quasar.dev) or why not become an [active Quasar project maintainer](contribution-guide/running-projects).
1111

1212
<team-listing class="q-mt-xl" />

0 commit comments

Comments
 (0)