Below are a list of ways that you can help contribute to this project, as well as policies and guides that explain how to get started.
Please review everything on this page before you submit your contribution.
Stuff happens, and sometimes as best as we try, there may be issues within this project that we are unaware of. That is the great thing about open-source; anyone can use the program and contribute to making it better.
If you have found a bug, have an issue, or maybe even a cool idea; you can let us know by submitting it. However, before you submit your new issue, bug report, or feature request; head over to the Issues Section and ensure nobody else has already submitted it.
Once you are sure that your issue has not already being dealt with; you may submit a new issue at here. You'll be asked to specify exactly what your new submission targets, such as:
- Bug report
- Feature Suggestion
When writing a new submission; 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.
If you are submitting a bug report:
- Explain the issue
- Describe how you expect for a feature to work, and what you're seeing instead of what you expected.
- List possible options for a resolution or insight
- Provide screenshots, logs, or anything else that can visually help track down the issue.
If you are looking to contribute to this project by actually 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.
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.
All contributions are made via pull requests. To create a pull request, you need a GitHub account. If you are unclear on this process, see GitHub's documentation on forking and pull requests. Pull requests should be targeted at the master branch.
- Follow the repository's code formatting conventions (see below);
- Include tests that prove that the change works as intended and does not add regressions;
- Document the changes in the code and/or the project's documentation;
- Your PR must pass the CI pipeline;
- When submitting your Pull Request, use one of the following branches:
- For bug fixes:
mainbranch - For features & functionality:
developmentbranch
- For bug fixes:
- Include a proper git commit message following the Conventional Commit Specification.
If you have completed the above tasks, 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.
Reviewers will approve the pull request once they are satisfied with the patch it will be merged.
When commiting your changes, we require you to follow the Conventional Commit Specification. 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:
<type>[(optional <scope>)]: <description>
[optional <body>]
[optional <footer(s)>]
| Type | Description |
|---|---|
feat |
Introduce new feature |
fix |
Bug fix |
deps |
Add or update existing dependencies |
docs |
Change website or markdown documents. Does not mean changes to the documentation generator script itself, only the documents created from the generator. E.g: documentation, readme.md or markdown |
build |
Changes to the build / compilation / packaging process or auxiliary tools such as doc generation E.g: create new build tasks, update release script, etc. |
test |
Add or refactor tests, no production code change. Changes the suite of automated tests for the app. |
perf |
Performance improvement of algorithms or execution time of the app. Does not change an existing feature. |
style |
Update / reformat style of source code. Does not change the way app is implemented. Changes that do not affect the meaning of the code E.g: white-space, formatting, missing semi-colons, change tabs to spaces, etc) |
refactor |
Change to production code that leads to no behavior difference, E.g: split files, rename variables, rename package, improve code style, etc. |
change |
Change an existing feature. |
chore |
Includes technical or preventative maintenance task that is necessary for managing the app or repo, such as updating grunt tasks, but is not tied to any specific feature. Usually done for maintanence purposes. E.g: Edit .gitignore, .prettierrc, .prettierignore, .gitignore, eslint.config.js file |
ci |
Changes related to Continuous Integration (usually yml and other configuration files). |
misc |
Anything that doesn't fit into another commit type. Usually doesn't change production code; yet is not ci, test or chore. |
revert |
Revert a previous commit |
remove |
Remove a feature from app. Features are usually first deprecated 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. |
deprecate |
Deprecate existing functionality, but does not remove it from the app. |
feat(core): bug affecting menu [#22]
^───^────^ ^────────────────^ ^───^
| | | |
| | | └───⫸ (ISSUE): Reference issue ID
│ │ │
│ │ └───⫸ (DESC): Summary in present tense. Use lower case not title case!
│ │
│ └───────────⫸ (SCOPE): The package(s) that this change affects
│
└───────────────⫸ (TYPE): See list above
<type>(<scope>): <short summary> [issue]
| | | |
| | | └─⫸ Reference issue id (optional)
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core|
│ elements|forms|http|language-service|localize|platform-browser|
│ platform-browser-dynamic|platform-server|router|service-worker|
│ upgrade|zone.js|packaging|changelog|docs-infra|migrations|ngcc|ve|
│ devtools....
│
└─⫸ Commit Type: build|ci|doc|docs|feat|fix|perf|refactor|test
website|chore|style|type|revert|deprecate
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.
References should be on their own line, following the word Ref or Refs
Title: fix(core): fix error message displayed to users. [#22]
Description: The description of your commit
Ref: #22, #34, #37
The following allows you to configure ESLint and Prettier.
We use the following packages for linting and prettier.
| Package | Repo File | Description |
|---|---|---|
| typescript-eslint | package.json | Tooling which enables you to use TypeScript with ESLint |
| eslint-plugin-prettier | package.json | Runs Prettier as an ESLint rule and reports differences as individual ESLint issues. |
| @typescript-eslint/parser | package.json | An ESLint parser which leverages TypeScript ESTree to allow for ESLint to lint TypeScript source code. |
| @typescript-eslint/eslint-plugin | package.json | An ESLint plugin which provides lint rules for TypeScript codebases. |
| @stylistic/eslint-plugin-js | package.json | JavaScript stylistic rules for ESLint, migrated from eslint core. |
| @stylistic/eslint-plugin-ts | package.json | TypeScript stylistic rules for ESLint, migrated from typescript-eslint. |
| @stylistic/eslint-plugin-plus | package.json | Supplementary rules introduced by ESLint Stylistic. |
| prettier | package.json | Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary. |
You can add the following to your package.json file:
"devDependencies": {
"eslint-plugin-prettier": "^5.1.3",
"typescript-eslint": "^7.14.0",
"@typescript-eslint/parser": "^7.16.0",
"@typescript-eslint/eslint-plugin": "^7.16.0",
"@stylistic/eslint-plugin-js": "^2.3.0",
"@stylistic/eslint-plugin-ts": "^2.3.0",
"@stylistic/eslint-plugin-plus": "^2.3.0",
"prettier": "^3.2.5"
},Within the root folder of the repo, there are several configuration files which you should be using within the project. These files dictate how prettier and eslint will behave and what is acceptable / not acceptable.
Pick the config file below depending on which version of ESLint you are using. The v8 and older .eslint may not be there if we have migrated over to an Eslint v9 flat config file:
-
obsidian-gistr/eslint.config.js
Lines 1 to 152 in 27ba6d6
-
printWidth: 120, tabWidth: 4, useTabs: false, semi: false, singleQuote: true, quoteProps: 'preserve', jsxSingleQuote: true, trailingComma: 'none', bracketSpacing: true, bracketSameLine: false, arrowParens: 'always', proseWrap: 'preserve', htmlWhitespaceSensitivity: 'ignore', endOfLine: 'auto', embeddedLanguageFormatting: 'auto', singleAttributePerLine: false, experimentalTernaries: false
When submitting your pull request, these linting and style rules will be verified with all of your files. If you did not follow these rules; the linter tests on your pull request will fail; and you'll be expected to correct these issues before your submission will be transferred over for human review.
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.
You may use block style commenting, or single lines:
/*
make platform writable
*/
Object.defineProperty(process, 'platform', {
value: platform,
writable: true
});
afterEach(() => {
process.platform = platform;
process.env.OSTYPE = OSTYPE;
});
/*
tests to decide if the end-user is running on Darwin or another platform.
*/
test(`Return true if platform is Darwin`, () => {
process.platform = 'darwin';
expect(bIsDarwin()).toBe(true);
});
test(`Return false if platform is not Darwin`, () => {
process.platform = 'linux';
expect(bIsDarwin()).toBe(false);
});When writing your code, ensure you stick to camelCase
let myVar = 'one';
let secondVar = 'two';For files that are not controlled by prettier or eslint; you should be using the Allman Style. This style puts the brace associated with a control statement on the next line, indented. Statements within the braces are indented to the same level as the braces.
return {
status: "failure",
user:
{
id: "1aaa35aa-fb3a-62ae-ffec-a14g7fc401ac",
label: "Test String",
}
};When writing your code, set your IDE to utilize spaces, with a configured size of 4 characters. If this project utilizes ESLint, you should find the file .editorconfig in the root directory of the repo which defines how the file should be formatted. Load that file into programs such as Visual Studio Code.