-
Notifications
You must be signed in to change notification settings - Fork 557
(DRAFT) Create an initial CODE_CONVENTIONS.md and CODE_STYLE.md (Frontend) #5938
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
lgeggleston
wants to merge
2
commits into
DSpace:main
Choose a base branch
from
lgeggleston:code_style_and_conventions
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| # DSpace Angular Code Conventions | ||
|
|
||
| DSpace has established coding conventions or best practices that all contributions must follow in order | ||
| to be accepted. | ||
|
|
||
| These code conventions describe the best practices for design and implementation of DSpace code, helping ensure that all DSpace components have a consistent layout and follow the essential Web Content Accessibility Guidelines ([WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/)). | ||
| The best practices for formatting your code are defined in our separate [Code Style Guidelines](CODE_STYLE.md). | ||
|
|
||
| For additional guidelines, see the wiki documentation for [User Interface Design Principles & Accessibility](https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408945765/User+Interface+Design+Principles+Accessibility). | ||
|
|
||
| 1. [Enforcement of Guidelines](#enforcement-of-guidelines) | ||
| 2. [Angular Guidelines](#angular-guidelines) | ||
| 1. [Templates in Base Theme should only use default Bootstrap styling](#templates-in-base-theme-should-only-use-default-Bootstrap-styling) | ||
| 2. [Required Bootstrap Components must use `ng-bootstrap` library](#required-bootstrap-components-must-use-ng-bootstrap-library) | ||
| 3. [Document methods and classes using TypeDoc](#document-methods-and-classes-using-typedoc) | ||
| 4. [Align with DSpace's User Interface Design Guidelines](#align-with-dspaces-user-interface-design-guidelines) | ||
| 3. [Accessibility Guidelines](#accessibility-guidelines) | ||
| 1. [Align with WCAG (Web Content Accessibility Guidelines) AA criteria](#align-with-wcag-web-content-accessibility-guidelines-aa-criteria) | ||
| 2. [Align with DSpace's User Interface Accessibility Guidelines](#align-with-dspaces-user-interface-accessibility-guidelines) | ||
|
|
||
|
|
||
| ## Enforcement of Guidelines | ||
|
|
||
| Enforcement of these code conventions is handled in two ways: | ||
| * Some guidelines are enforced strictly via static code tools such as ESLint. Where possible, we prefer to automate enforcement. | ||
| * All guidelines are enforced during code review by the assigned reviewers. | ||
|
|
||
| ## Angular Guidelines | ||
|
|
||
| ### Templates in Base Theme should only use default Bootstrap styling | ||
|
|
||
| All templates in the Base Theme ([/src/app](/src/app) directories) should only use default Bootstrap styling. Documentation at: https://getbootstrap.com/docs/4.6/getting-started/introduction/ | ||
| * Exceptions may be made for accessibility purposes. For example, Bootstrap notes their [default color scheme does not always have sufficient color contrast](https://getbootstrap.com/docs/4.0/getting-started/accessibility/#color-contrast). | ||
|
|
||
| ### Required Bootstrap Components must use `ng-bootstrap` library | ||
|
|
||
| When Bootstrap Components (accordion, dropdown, etc …) are required you MUST use the included `ng-bootstrap` library. Documentation at: https://ng-bootstrap.github.io/#/components/accordion/examples | ||
|
|
||
| ### Document methods and classes using TypeDoc | ||
|
|
||
| Write [TypeDoc](https://typedoc.org/) comments for all new (or modified) public methods and classes, as well as for large or complex private methods. | ||
|
|
||
| ### Align with DSpace's User Interface Design Guidelines | ||
|
|
||
| In order to ensure consistent layout and behavior on all pages, please refer to the [User Interface Design Guidelines](https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408945765/User+Interface+Design+Principles+Accessibility#UserInterfaceDesignPrinciples%26Accessibility-UserInterfaceDesignGuidelines). This documentation provides more details regarding User Interface layout/design and the elements (or components) used by the DSpace User Interface. | ||
|
|
||
| ## Accessibility Guidelines | ||
|
|
||
| ### Align with WCAG (Web Content Accessibility Guidelines) AA criteria | ||
|
|
||
| The DSpace User Interface strives to align with [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) AA criteria. Some AAA criteria may also be supported. For more information see [Accessibility documentation](https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408944958/Accessibility). | ||
|
lgeggleston marked this conversation as resolved.
|
||
|
|
||
| The use of the Bootstrap framework can help in achieving some WCAG goals such as ‘Visual Presentation’ (AAA), 'Parsing' (A), ‘Orientation’ (AA), ‘Reflow’ (AA) and ‘Text Spacing’ (AA). See the Bootstrap chapter ["Accessibility"](https://getbootstrap.com/docs/4.0/getting-started/accessibility/) for an explanation of WCAG and where to find additional information. | ||
|
|
||
| ### Align with DSpace's User Interface Accessibility Guidelines | ||
|
|
||
| Refer to the [User Interface Accessibility Guidelines](https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408945765/User+Interface+Design+Principles+Accessibility#UserInterfaceDesignPrinciples%26Accessibility-UserInterfaceAccessibilityGuidelines) for more detailed recommendations regarding HTML structure, ARIA labelling and more. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # DSpace Angular/Typescript Code Style Guidelines | ||
|
|
||
| DSpace has established code style / code formatting guidelines that all contributions must follow in order | ||
| to be accepted. | ||
|
|
||
| These code style guidelines describe the best practices for formatting your code. The best practices for design and implementation of your code are defined in our separate [Code Conventions](CODE_CONVENTIONS.md). | ||
|
|
||
| * [Enforcement of Guidelines](#enforcement-of-guidelines) | ||
| * [TypeScript Style Guide](#typescript-style-guide) | ||
| * [Angular Style Guide](#angular-style-guide) | ||
| * [IDE Support](#ide-support) | ||
|
|
||
|
|
||
| ## Enforcement of Guidelines | ||
|
|
||
| Enforcement is handled by [ESLint](https://eslint.org/) using the configuration file in the root source directory: [.eslintrc.json](.eslintrc.json). | ||
|
|
||
| If you would like to pre-check your Pull Request for any Code Style issues, you can do so by running: | ||
|
|
||
| ``` | ||
| npm run lint | ||
| ``` | ||
|
|
||
| Code contributions may only suppress these rules if pre-approved. Code may suppress these rules by using [ESLint configuration comments](https://eslint.org/docs/latest/use/configure/rules#use-configuration-comments-1), for example `/* eslint-disable [rule-name] */`. | ||
|
|
||
| The DSpace TypeScript Style Guide is enforced on all Pull Requests to the "main" branch in `dspace-angular`. Therefore, if a Pull Request to the "main" branch does not align with the Style Guide, it will fail the build process within our GitHub CI. | ||
|
|
||
| ## TypeScript Style Guide | ||
|
|
||
| For the DSpace Angular UI (written in TypeScript), we use [ESLint](https://eslint.org/) to validate the style of all Typescript (*.ts) files. | ||
| All style rules are defined in [.eslintrc.json](.eslintrc.json). | ||
|
|
||
| ## Angular Style Guide | ||
|
|
||
| Follow the [official Angular style guide](https://angular.dev/style-guide). It contains guidelines for naming files, directory structure, etc. | ||
|
|
||
| ## IDE Support | ||
|
|
||
| Most IDEs include an ESLint plugin which can automatically enforce the defined style rules in your Typescript code. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.