|
| 1 | +# graphql-flutter HACKING guide |
| 2 | + |
| 3 | +## Table of Content |
| 4 | + |
| 5 | +- Introduction |
| 6 | +- Code Style |
| 7 | +- Commit Style |
| 8 | +- How make the release |
| 9 | + |
| 10 | +## Introduction |
| 11 | + |
| 12 | +Welcome in the HACKING guide and how a day in a graphql-flutter maintainer looks like. |
| 13 | + |
| 14 | +After this reading you should be ready to contribute to the repository and also be one of |
| 15 | +the next maintainer in the future if you would like! |
| 16 | + |
| 17 | +Let's begin |
| 18 | + |
| 19 | +## Code style |
| 20 | + |
| 21 | +To ensure consistency throughout the source code, keep these rules in mind as you are working: |
| 22 | + |
| 23 | +- All features or bug fixes **must be tested** by one or more specs (unit-tests). |
| 24 | +- All public API methods **must be documented**. (Details TBC). |
| 25 | +- We follow [Effective Dart: Style Guidelines][dart-style-guide]. |
| 26 | + |
| 27 | +### If You Don’t Know The Right Thing, Do The Simplest Thing |
| 28 | +Sometimes the right way is unclear, so it’s best not to spend time on it. It’s far easier to rewrite simple code than complex code, too. |
| 29 | + |
| 30 | +### Use of `FIXME` |
| 31 | + |
| 32 | +There are two cases in which you should use a `/* FIXME: */` |
| 33 | +comment: one is where an optimization is possible, but it’s not clear that it’s yet worthwhile, |
| 34 | +and the second one is to note an ugly corner case which could be improved (and may be in a following patch). |
| 35 | + |
| 36 | +There are always compromises in code: eventually it needs to ship. `FIXME` is grep-fodder for yourself and others, |
| 37 | +as well as useful warning signs if we later encounter an issue in some part of the code. |
| 38 | + |
| 39 | +### Write For Today: Unused Code Is Buggy Code |
| 40 | + |
| 41 | +Don’t overdesign: complexity is a killer. If you need a fancy data structure, start with a brute force linked list. Once that’s working, |
| 42 | +perhaps consider your fancy structure, but don’t implement a generic thing. Use `/* FIXME: ...*/` to salve your conscience. |
| 43 | + |
| 44 | +### Keep Your Patches Reviewable |
| 45 | +Try to make a single change at a time. It’s tempting to do “drive-by” fixes as you see other things, and a minimal amount is unavoidable, |
| 46 | +but you can end up shaving infinite yaks. This is a good time to drop a `/* FIXME: ...*/` comment and move on. |
| 47 | + |
| 48 | + |
| 49 | +## Commit Style |
| 50 | + |
| 51 | +The commit style is one of the more important concept to manage a monorepo like graphql-flutter, amd In particular |
| 52 | +the commit style are used to generate the changelog for the next release. |
| 53 | + |
| 54 | +The commits will follow a dart community guideline with the following rules. |
| 55 | + |
| 56 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 57 | +format that includes a **type**, a **scope** and a **subject**: |
| 58 | + |
| 59 | +``` |
| 60 | +<type>(<scope>): <subject> |
| 61 | +<BLANK LINE> |
| 62 | +<body> |
| 63 | +<BLANK LINE> |
| 64 | +<footer> |
| 65 | +``` |
| 66 | + |
| 67 | +The **header** is mandatory and the **scope** of the header is optional. |
| 68 | + |
| 69 | +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier |
| 70 | +to read on GitHub as well as in various git tools. |
| 71 | + |
| 72 | +The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any. |
| 73 | + |
| 74 | +A coupled of examples are: |
| 75 | + |
| 76 | +``` |
| 77 | +docs(changelog): update changelog to beta.5 |
| 78 | +``` |
| 79 | + |
| 80 | +``` |
| 81 | +fix(release): need to depend on latest rxjs and zone.js |
| 82 | +
|
| 83 | +The version in our package.json gets copied to the one we publish, and users need the latest of these. |
| 84 | +``` |
| 85 | + |
| 86 | +### Types |
| 87 | + |
| 88 | +- **feat**: A new feature |
| 89 | +- **fix**: A bug fix |
| 90 | + |
| 91 | +### Scopes |
| 92 | + |
| 93 | +- **graphql**: Changes related to the graphql client |
| 94 | +- **graphql_flutter**: Changes related to the graphql_flutter package |
| 95 | + |
| 96 | + |
| 97 | +### Subject |
| 98 | + |
| 99 | +The subject contains a succinct description of the change: |
| 100 | + |
| 101 | +- use the imperative, present tense: "change" not "changed" nor "changes" |
| 102 | +- don't capitalize the first letter |
| 103 | +- no dot (.) at the end |
| 104 | + |
| 105 | +### Body |
| 106 | + |
| 107 | +You are free to put all the content that you want inside the body, but if you are fixing |
| 108 | +an exception or some wrong behavior you must put the details or stacktrace inside the body to make sure that |
| 109 | +it is indexed from the search engine. |
| 110 | + |
| 111 | +An example of commit body is the following one |
| 112 | + |
| 113 | +``` |
| 114 | +checker: fixes overloading operation when the type is optimized |
| 115 | +
|
| 116 | +The stacktrace is the following one |
| 117 | +
|
| 118 | +} expected `Foo` not `Foo` - both operands must be the same type for operator overloading |
| 119 | + 11 | } |
| 120 | + 12 | |
| 121 | + 13 | fn (_ Foo) == (_ Foo) bool { |
| 122 | + | ~~~ |
| 123 | + 14 | return true |
| 124 | + 15 | } |
| 125 | +
|
| 126 | +
|
| 127 | +Signed-off-by: Vincenzo Palazzo <[email protected]> |
| 128 | +``` |
| 129 | + |
| 130 | +## How make the release |
| 131 | + |
| 132 | +This is the most funny part, and also is the most difficult one in a monorepo repository. |
| 133 | + |
| 134 | +In particular, graphql-flutter has the possibility to release one single package at the time, or |
| 135 | +all together. |
| 136 | + |
| 137 | +To prepare the release the following steps are required: |
| 138 | + |
| 139 | +- Bump the version number in the package before the release; |
| 140 | +- Generate the changelog related to the package: |
| 141 | + - We use the [changelog.dat](https://github.com/vincenzopalazzo/changelog.dart/releases) to generate the correct CHANGELOG from the Github API. |
| 142 | + - To use the changelog tools you need to run the following commands inside the package directory |
| 143 | +``` |
| 144 | +export GITHUB_TOKEN="your_token" |
| 145 | +changelog-cli -p {package_name} -v v{version_number} -g zino-hofmann/graphql-flutter -b main -m header |
| 146 | +# create the CHANGELOG.md file, if already exist it will join the result, so it is important ran the tool inside the package directory |
| 147 | +``` |
| 148 | +- Make the Github release: To release a single package we need to create a release with the following tag `{package_name}-v{version_number}`, and |
| 149 | +if we make a release with the tag `v{version_number}` this will release all the packages (useful for a major release of the package). |
| 150 | + |
| 151 | +>Programs must be written for people to read, and only incidentally for machines to execute. |
| 152 | +> - Someone |
| 153 | +
|
| 154 | +Cheers! |
| 155 | + |
| 156 | +[Vincent](https://github.com/vincenzopalazzo) |
0 commit comments