Skip to content

Commit d44df96

Browse files
alestiagoscarlettelizarenancaraujo
authored
docs: include CONTRIBUTING.md for dart_frog_cli (#648)
* docs: include dart_frog_cli contributing * docs: improved commands * docs: improved grammar * docs: added Understanding Dart Frog CLI * docs: included very_good_cli installation * docs: link to very good cli page * docs: typo * Apply suggestions from code review Co-authored-by: Scarlett Eliza <[email protected]> * Update packages/dart_frog_cli/CONTRIBUTING.md * Update packages/dart_frog_cli/CONTRIBUTING.md Co-authored-by: Renan <[email protected]> * docs: added link to templates * docs: linked to code * docs: command refactoring * docs: removed : --------- Co-authored-by: Scarlett Eliza <[email protected]> Co-authored-by: Renan <[email protected]>
1 parent d37a5ab commit d44df96

File tree

1 file changed

+134
-0
lines changed

1 file changed

+134
-0
lines changed

‎packages/dart_frog_cli/CONTRIBUTING.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# 🦄 Contributing to Dart Frog CLI
2+
3+
First of all, thank you for taking the time to contribute! 🎉👍 Before you do, please carefully read this guide.
4+
5+
## Understanding Dart Frog CLI
6+
7+
The Dart Frog CLI is a [`CommandRunner`](https://pub.dev/documentation/args/latest/command_runner/CommandRunner-class.html) that exposes some commands such as:
8+
9+
- `build`: Creates a production build by using the [`dart_frog_prod_server`](../../bricks/dart_frog_prod_server/) brick to generate the files; see [`BuildCommand`](lib/src/commands/build/build.dart).
10+
- `create`: Creates a new Dart Frog app by using the [`dart_frog_new`](../../bricks/dart_frog_new/) brick to generate the files; see [`CreateCommand`](lib/src/commands/create/create.dart).
11+
- `dev`: Runs a local development server at a given port and listens to file changes, generating new files using the [`dart_frog_dev_server`](../../bricks/dart_frog_dev_server/) brick on updates; see [`DevCommand`](lib/src/commands/dev/dev.dart).
12+
- `update`: Updates the Dart Frog CLI's if possible; see [`UpdateCommand`](lib/src/commands/update/update.dart).
13+
14+
💡 **Note**: Dart Frog CLI's completion functionality is powered by [CLI Completion](https://github.com/VeryGoodOpenSource/cli_completion).
15+
16+
## Opening an issue
17+
18+
We highly recommend [creating an issue][bug_report_link] if you have found a bug, want to suggest a feature, or recommend a change. Please do not immediately open a pull request. Opening an issue first allows us to reach an agreement on a fix before you put significant effort into a pull request.
19+
20+
When reporting a bug, please use the built-in [Bug Report][bug_report_link] template and provide as much information as possible including detailed reproduction steps. Once one of the package maintainers has reviewed the issue and we reach an agreement on the fix, open a pull request.
21+
22+
## Developing for Dart Frog CLI
23+
24+
To develop for Dart Frog CLI you will need to become familiar with Very Good Ventures processes and conventions:
25+
26+
### Setting up your local development environment
27+
28+
1. Install a valid [Dart SDK](https://dart.dev/get-dart) in your local environment. Compatible Dart SDK versions with test optimizer can be found [here](https://github.com/VeryGoodOpenSource/very_good_cli/blob/main/pubspec.yaml). If you have Flutter installed, you likely have a valid Dart SDK version already installed.
29+
30+
2. Install [Very Good CLI](https://github.com/VeryGoodOpenSource/very_good_cli):
31+
32+
```sh
33+
# 💻 Install Very Good CLI globally
34+
dart pub global activate very_good_cli
35+
```
36+
37+
3. Install all Dart Frog CLI's dependencies:
38+
39+
```sh
40+
# 📂 Get project dependencies recursively with Dart Frog CLI's (from project root)
41+
very_good packages get -r --ignore="bricks/**"
42+
```
43+
44+
3. Run all Dart Frog CLI's tests:
45+
46+
```sh
47+
# 🧪 Run Dart Frog CLI's unit tests (from packages/dart_frog_cli)
48+
dart test
49+
50+
# 🧪💻 Run Dart Frog CLI's end to end test (from packages/dart_frog_cli/e2e)
51+
dart test
52+
```
53+
54+
If some tests do not pass out of the box, please submit an [issue](https://github.com/VeryGoodOpenSource/dart_frog/issues/new/choose).
55+
56+
4. Install your own version of Dart Frog CLI in your local environment:
57+
58+
```sh
59+
# 🚀 Activate your own local version of Dart Frog CLI (from packages/dart_frog_cli)
60+
dart pub global activate --source path .
61+
```
62+
63+
5. If you are modifying any [templates](../../bricks), make sure to bundle them before activating:
64+
65+
```sh
66+
# 📦 Bundle templates (from root)
67+
tool/generate_bundles.sh
68+
```
69+
70+
### Creating a Pull Request
71+
72+
Before creating a Pull Request please:
73+
74+
1. [Fork](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) the [GitHub repository](https://github.com/VeryGoodOpenSource/dart_frog) and create your branch from `main`:
75+
76+
```sh
77+
# 🪵 Branch from `main`
78+
git branch <branch-name>
79+
git checkout <branch-name>
80+
```
81+
82+
Where `<branch-name>` is an appropriate name describing your change.
83+
84+
2. Install dependencies:
85+
86+
```sh
87+
# 📂 Get project dependencies recursively with Dart Frog CLI
88+
very_good packages get -r --ignore="bricks/**"
89+
```
90+
91+
3. Ensure you have a meaningful [semantic][conventional_commits_link] commit message.
92+
93+
4. Add tests! Pull Requests without 100% test coverage will **not** be merged. If you're unsure on how to do so watch our [Testing Fundamentals Course](https://www.youtube.com/watch?v=M_eZg-X789w&list=PLprI2satkVdFwpxo_bjFkCxXz5RluG8FY).
94+
95+
5. Ensure the existing test suite passes locally:
96+
97+
```sh
98+
# 🧪 Run Dart Frog CLI's unit test (from packages/dart_frog_cli)
99+
dart test
100+
```
101+
102+
6. Format your code:
103+
104+
```sh
105+
# 🧼 Run Dart's formatter
106+
dart format .
107+
```
108+
109+
7. Analyze your code:
110+
111+
```sh
112+
# 🔍 Run Dart's analyzer
113+
dart analyze --fatal-infos --fatal-warnings .
114+
```
115+
116+
Some analysis issues may be fixed automatically with:
117+
118+
```sh
119+
# Automatically fix analysis issues that have associated automated fixes
120+
dart fix --apply
121+
```
122+
123+
💡 **Note**: Our repositories use [Very Good Analysis](https://github.com/VeryGoodOpenSource/very_good_analysis).
124+
125+
8. Create the Pull Request with a meaningful description, linking to the original issue where possible.
126+
127+
9. Verify that all [status checks](https://github.com/VeryGoodOpenSource/dart_frog/actions) are passing for your Pull Request once they have been approved to run by a maintainer.
128+
129+
💡 **Note**: While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional work, tests, or other changes before your pull request can be accepted.
130+
131+
[conventional_commits_link]: https://www.conventionalcommits.org/en/v1.0.0
132+
[bug_report_link]: https://github.com/VeryGoodOpenSource/dart_frog/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=fix%3A+
133+
[very_good_core_link]: doc/very_good_core.md
134+
[very_good_ventures_link]: https://verygood.ventures/?utm_source=github&utm_medium=banner&utm_campaign=CLI

0 commit comments

Comments
 (0)