|
| 1 | +<div align="center"> |
| 2 | +<h1>⭕ Contributor Guide ⭕</h1> |
| 3 | +<br /> |
| 4 | +<p>A brief overview of contributing to this repo.</p> |
| 5 | + |
| 6 | +<br /> |
| 7 | + |
| 8 | +</div> |
| 9 | + |
| 10 | +<div align="center"> |
| 11 | + |
| 12 | +<!-- prettier-ignore-start --> |
| 13 | +[![Version][badge-version-gh]][link-version-gh] [![Size][badge-size-gh]][badge-size-gh] [![Last Commit][badge-commit]][badge-commit] [![Contributors][badge-all-contributors]](#contributors-) |
| 14 | +<!-- prettier-ignore-end --> |
| 15 | + |
| 16 | +</div> |
| 17 | + |
| 18 | +<br /> |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +<br /> |
| 23 | + |
| 24 | +## Table of Contents |
| 25 | + |
| 26 | +- [Table of Contents](#table-of-contents) |
| 27 | +- [Issues, Bugs, Ideas](#issues-bugs-ideas) |
| 28 | +- [Development](#development) |
| 29 | + - [Before Submitting Pull Requests](#before-submitting-pull-requests) |
| 30 | + - [Conventional Commit Specification](#conventional-commit-specification) |
| 31 | + - [Types](#types) |
| 32 | + - [Example 1:](#example-1) |
| 33 | + - [Example 2:](#example-2) |
| 34 | + - [Referencing Issues](#referencing-issues) |
| 35 | + - [Vertical alignment](#vertical-alignment) |
| 36 | + - [Spaces Instead Of Tabs](#spaces-instead-of-tabs) |
| 37 | + - [Commenting](#commenting) |
| 38 | + - [Casing](#casing) |
| 39 | + |
| 40 | + |
| 41 | +<br /> |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +<br /> |
| 46 | + |
| 47 | +## Issues, Bugs, Ideas |
| 48 | +Stuff happens, and sometimes as best as we try, there may be issues with these Obsidian snippets that we are unaware of. That is the great thing about open-source; anyone can use the program and contribute to making it better. |
| 49 | + |
| 50 | +<br /> |
| 51 | + |
| 52 | +If you have found a bug, have an issue with these snippets, or maybe even a cool idea; you can let us know by [submitting it](https://github.com/Aetherinox/obsidian-dataview-snippets/issues). However, before you submit your new issue, bug report, or feature request; head over to the [Issues Section](https://github.com/Aetherinox/obsidian-dataview-snippets/issues) and ensure nobody else has already submitted it. |
| 53 | + |
| 54 | +<br /> |
| 55 | + |
| 56 | +Once you are sure that your issue is not already being dealt with; you may submit it by clicking [here](https://github.com/Aetherinox/obsidian-dataview-snippets/issues/new/choose). You'll be asked to specify exactly what your new submission targets, such as: |
| 57 | +- Bug report |
| 58 | +- Feature Suggestion |
| 59 | + |
| 60 | +<br /> |
| 61 | + |
| 62 | +When submitting your new report, ensure you fill out any of the questions asked of you. If you do not provide enough information, we cannot help. Be as detailed as possible, and provide any logs or screenshots you may have to help us better understand what you mean. Failure to fill out the submission properly may result in it being closed without a response. |
| 63 | + |
| 64 | +<br /> |
| 65 | + |
| 66 | +If you are submitting a bug report: |
| 67 | + |
| 68 | +- Explain the issue in detail |
| 69 | +- Describe how you expect for a feature to work, and what you're seeing instead of what you expected. |
| 70 | +- Provide screenshots, logs, or anything else that can visually help track down the issue. |
| 71 | + |
| 72 | +<br /> |
| 73 | + |
| 74 | +<div align="center"> |
| 75 | + |
| 76 | +[](https://github.com/Aetherinox/obsidian-dataview-snippets/issues) |
| 77 | + |
| 78 | +</div> |
| 79 | + |
| 80 | +<br /> |
| 81 | + |
| 82 | +<div align="center"> |
| 83 | + |
| 84 | +**[`^ back to top ^`](#table-of-contents)** |
| 85 | + |
| 86 | +</div> |
| 87 | + |
| 88 | +<br /> |
| 89 | + |
| 90 | +--- |
| 91 | + |
| 92 | +<br /> |
| 93 | + |
| 94 | +<br /> |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +<br /> |
| 99 | + |
| 100 | +## Development |
| 101 | +If you are looking to contribute to these Obsidian snippets and submit your own code; please review this section completely. There is important information and policies provided below that you must follow for your pull request to get accepted. |
| 102 | + |
| 103 | +The source is here for everyone to collectively share and colaborate on. If you think you have a possible solution to a problem; don't be afraid to get your hands dirty. |
| 104 | + |
| 105 | +All contributions are made via **Pull Requests**. To make a pull request, you will need a GitHub account; if you are unclear on this process, see GitHub's documentation on forking and pull requests. |
| 106 | + |
| 107 | +<br /> |
| 108 | + |
| 109 | +### Before Submitting Pull Requests |
| 110 | + |
| 111 | +- Follow the repository's code formatting conventions (see below); |
| 112 | +- Include tests that prove that the change works as intended and does not add regressions; |
| 113 | +- Document the changes in the code and/or the project's documentation; |
| 114 | +- Your PR must pass the CI pipeline; |
| 115 | +- When submitting your Pull Request, use one of the following branches: |
| 116 | + - For bug fixes: `main` branch |
| 117 | + - For features & functionality: `development` branch |
| 118 | +- Include a proper git commit message following the [Conventional Commit Specification](https://www.conventionalcommits.org/en/v1.0.0/#specification). |
| 119 | + |
| 120 | +<br /> |
| 121 | + |
| 122 | +If all of these items are checked, the pull request is ready to be reviewed and your pull request's label will be changed to "Ready for Review". At this point, a human will need to step in and manually verify your submission. |
| 123 | + |
| 124 | +Once your submission has been tested and verified; it will be merged. |
| 125 | + |
| 126 | +<br /> |
| 127 | + |
| 128 | +### Conventional Commit Specification |
| 129 | + |
| 130 | +When commiting your changes, we require you to follow the Conventional Commit Specification, described below. |
| 131 | + |
| 132 | +**The Conventional Commits** is a specification for the format and content of a commit message. The concept behind Conventional Commits is to provide a rich commit history that can be read and understood by both humans and automated tools. Conventional Commits have the following format: |
| 133 | + |
| 134 | +<br /> |
| 135 | + |
| 136 | +``` |
| 137 | +<type>[(optional <scope>)]: <description> |
| 138 | +
|
| 139 | +[optional <body>] |
| 140 | +
|
| 141 | +[optional <footer(s)>] |
| 142 | +``` |
| 143 | + |
| 144 | +#### Types |
| 145 | +| Type | Description | |
| 146 | +| --- | --- | |
| 147 | +| `feat` | Introduces a new feature | |
| 148 | +| `fix` | Bug fix for the end-user | |
| 149 | +| `deps` | Specifically targets adding new or updating existing dependencies | |
| 150 | +| `docs` | Change to the website or Markdown documents | |
| 151 | +| `build` | Alters the build process. E.g: creating a new build task, updating the release script, etc. | |
| 152 | +| `test` | Adds or refactors tests, no production code change. Usually changes the suite of automated tests for the app. | |
| 153 | +| `perf` | Improves performance of algorithms or general execution time of the app, but does not fundamentally change an existing feature. | |
| 154 | +| `style` | Updates or reformats the style of the source code, but does not otherwise change the way the app is implemented. Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) | |
| 155 | +| `refactor` | Change to production code that leads to no behavior difference, E.g. splitting files, renaming internal variables, improving code style, etc. | |
| 156 | +| `change` | Changes to an existing feature. | |
| 157 | +| `chore` | Includes a technical or preventative maintenance task that is necessary for managing the app or the repo, such as updating grunt tasks, but is not tied to any specific feature. Usually done for maintanence purposes. | |
| 158 | +| `ci` | Changes related to Continuous Integration (usually `yml` and other configuration files). | |
| 159 | +| `misc` | Anything else that doesn't fit into another commit type. Usually doesn't change production code; yet is not ci, test or chore. | |
| 160 | +| `revert` | Revert a previous commit | |
| 161 | +| `remove` | Removes a feature from the app. Typically features are deprecated first for a period of time before being removed. Removing a feature from the app may be considered a breaking change that will require a major version number increment. | |
| 162 | +| `deprecate` | Deprecates existing functionality, but does not remove it from the app. | |
| 163 | + |
| 164 | +<br /> |
| 165 | + |
| 166 | +##### Example 1: |
| 167 | + |
| 168 | +``` |
| 169 | +feat(toc1): add ability to filter out certain headers from displaying |
| 170 | +^───^────^ ^────────────────────────────────^ |
| 171 | +│ │ │ |
| 172 | +│ │ └───⫸ (DESC): Summary in present tense. Use lower case not title case! |
| 173 | +│ │ |
| 174 | +│ └───────────⫸ (SCOPE): The package(s) that this change affects |
| 175 | +│ |
| 176 | +└───────────────⫸ (TYPE): See list above |
| 177 | +``` |
| 178 | + |
| 179 | +<br /> |
| 180 | + |
| 181 | +##### Example 2: |
| 182 | +``` |
| 183 | +<type>(<scope>): <short summary> |
| 184 | + │ │ │ |
| 185 | + │ │ └─⫸ Summary in present tense. Not capitalized. No period at the end. |
| 186 | + │ │ |
| 187 | + │ └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core| |
| 188 | + │ elements|forms|http|language-service|localize|platform-browser| |
| 189 | + │ platform-browser-dynamic|platform-server|router|service-worker| |
| 190 | + │ upgrade|zone.js|packaging|changelog|docs-infra|migrations|ngcc|ve| |
| 191 | + │ devtools.... |
| 192 | + │ |
| 193 | + └─⫸ Commit Type: build|ci|doc|docs|feat|fix|perf|refactor|test |
| 194 | + website|chore|style|type|revert|deprecate |
| 195 | +``` |
| 196 | + |
| 197 | +<br /> |
| 198 | + |
| 199 | +### Referencing Issues |
| 200 | +If you are pushing a commit which addresses a submitted issue, reference your issue at the end of the commit message. You may also optionally add the major issue to the end of your commit body. |
| 201 | + |
| 202 | +References should be on their own line, following the word `Ref` or `Refs` |
| 203 | + |
| 204 | +``` |
| 205 | +Title: fix(snippet): list of headers not rendering properly [#2002] |
| 206 | +Description: The description of your commit |
| 207 | +
|
| 208 | + Ref: #2002, #3004, #3007 |
| 209 | +``` |
| 210 | + |
| 211 | +<br /> |
| 212 | + |
| 213 | +### Vertical alignment |
| 214 | +Align similar elements vertically, to make typo-generated bugs more obvious |
| 215 | + |
| 216 | +```typescript |
| 217 | +let count = 0; |
| 218 | +const path_base = dv.current().file.path |
| 219 | +const path_targ = path_base.substr(0, path_base.lastIndexOf("/")); |
| 220 | +const path_sub = "" |
| 221 | + |
| 222 | +const filter_page = '"' + path_targ + "" + path_sub + '"'; |
| 223 | +const filter_folder = path_targ + path_sub; |
| 224 | +``` |
| 225 | + |
| 226 | +<br /> |
| 227 | + |
| 228 | +### Spaces Instead Of Tabs |
| 229 | +When writing your code, set your IDE to utilize **spaces**, with a configured tab size of `4 characters`. |
| 230 | + |
| 231 | +<br /> |
| 232 | + |
| 233 | +### Commenting |
| 234 | +Comment your code. If someone else comes along, they should be able to do a quick glance and have an idea of what is going on. Plus it helps novice readers to better understand the process. |
| 235 | + |
| 236 | +You may use block style commenting, or single lines: |
| 237 | + |
| 238 | +```typescript |
| 239 | +/* |
| 240 | + displays 'No Results' if user has absolutely no matching headers to show |
| 241 | +*/ |
| 242 | + |
| 243 | +if (count === 0) |
| 244 | +{ |
| 245 | + const rootNode = dv.el("div", "No results", { cls: "toc_results_none" }); |
| 246 | + rootNode.setAttribute("style", "text-align:center;"); |
| 247 | +} |
| 248 | +``` |
| 249 | + |
| 250 | +<br /> |
| 251 | + |
| 252 | +### Casing |
| 253 | +When writing your code, ensure you stick to `camelCase` |
| 254 | + |
| 255 | +```javascript |
| 256 | +let myVar = 'one'; |
| 257 | +let secondVar = 'two'; |
| 258 | +``` |
| 259 | + |
| 260 | +<br /> |
| 261 | + |
| 262 | +<br /> |
| 263 | +<br /> |
| 264 | + |
| 265 | +<!-- prettier-ignore-start --> |
| 266 | +<!-- BADGE > GENERAL --> |
| 267 | +[link-general-npm]: https://npmjs.com |
| 268 | +[link-general-nodejs]: https://nodejs.org |
| 269 | +[link-npmtrends]: http://npmtrends.com/obsidian-gistr |
| 270 | +<!-- BADGE > VERSION > GITHUB --> |
| 271 | +[badge-version-gh]: https://img.shields.io/github/v/tag/Aetherinox/obsidian-dataview-snippets?logo=GitHub&label=Version&color=ba5225 |
| 272 | +[link-version-gh]: https://github.com/Aetherinox/obsidian-dataview-snippets/releases |
| 273 | +<!-- BADGE > VERSION > NPMJS --> |
| 274 | +[badge-version-npm]: https://img.shields.io/npm/v/obsidian-gistr?logo=npm&label=Version&color=ba5225 |
| 275 | +[link-version-npm]: https://npmjs.com/package/obsidian-gistr |
| 276 | +<!-- BADGE > LICENSE --> |
| 277 | +[badge-license-mit]: https://img.shields.io/badge/MIT-FFF?logo=creativecommons&logoColor=FFFFFF&label=License&color=9d29a0 |
| 278 | +[link-license-mit]: https://github.com/Aetherinox/obsidian-dataview-snippets/blob/main/LICENSE |
| 279 | +<!-- BADGE > BUILD --> |
| 280 | +[badge-build]: https://img.shields.io/github/actions/workflow/status/Aetherinox/obsidian-dataview-snippets/release-npm.yml?logo=github&logoColor=FFFFFF&label=Build&color=%23278b30 |
| 281 | +[link-build]: https://github.com/Aetherinox/obsidian-dataview-snippets/actions/workflows/release-npm.yml |
| 282 | +<!-- BADGE > DOWNLOAD COUNT --> |
| 283 | +[badge-downloads-gh]: https://img.shields.io/github/downloads/Aetherinox/obsidian-dataview-snippets/total?logo=github&logoColor=FFFFFF&label=Downloads&color=376892 |
| 284 | +[link-downloads-gh]: https://github.com/Aetherinox/obsidian-dataview-snippets/releases |
| 285 | +[badge-downloads-npm]: https://img.shields.io/npm/dw/%40aetherinox%2Fmarked-alert-fa?logo=npm&&label=Downloads&color=376892 |
| 286 | +[link-downloads-npm]: https://npmjs.com/package/obsidian-gistr |
| 287 | +<!-- BADGE > DOWNLOAD SIZE --> |
| 288 | +[badge-size-gh]: https://img.shields.io/github/repo-size/Aetherinox/obsidian-dataview-snippets?logo=github&label=Size&color=59702a |
| 289 | +[link-size-gh]: https://github.com/Aetherinox/obsidian-dataview-snippets/releases |
| 290 | +[badge-size-npm]: https://img.shields.io/npm/unpacked-size/obsidian-gistr/latest?logo=npm&label=Size&color=59702a |
| 291 | +[link-size-npm]: https://npmjs.com/package/obsidian-gistr |
| 292 | +<!-- BADGE > COVERAGE --> |
| 293 | +[badge-coverage]: https://img.shields.io/codecov/c/github/Aetherinox/obsidian-dataview-snippets?token=MPAVASGIOG&logo=codecov&logoColor=FFFFFF&label=Coverage&color=354b9e |
| 294 | +[link-coverage]: https://codecov.io/github/Aetherinox/obsidian-dataview-snippets |
| 295 | +<!-- BADGE > ALL CONTRIBUTORS --> |
| 296 | +[badge-all-contributors]: https://img.shields.io/github/all-contributors/Aetherinox/obsidian-dataview-snippets?logo=contributorcovenant&color=de1f6f&label=contributors |
| 297 | +[link-all-contributors]: https://github.com/all-contributors/all-contributors |
| 298 | +[badge-tests]: https://img.shields.io/github/actions/workflow/status/Aetherinox/marked-alert-fa/npm-tests.yml?logo=github&label=Tests&color=2c6488 |
| 299 | +[link-tests]: https://github.com/Aetherinox/obsidian-dataview-snippets/actions/workflows/tests.yml |
| 300 | +[badge-commit]: https://img.shields.io/github/last-commit/Aetherinox/obsidian-dataview-snippets?logo=conventionalcommits&logoColor=FFFFFF&label=Last%20Commit&color=313131 |
| 301 | +[link-commit]: https://github.com/Aetherinox/obsidian-dataview-snippets/commits/main/ |
| 302 | +<!-- prettier-ignore-end --> |
0 commit comments