Merge pull request DSpace#5938 from lgeggleston/code_style_and_conventions

Create an initial CODE_CONVENTIONS.md and CODE_STYLE.md (Frontend)

Author: tdonohue

.github/pull_request_template.md

@@ -21,11 +21,12 @@ However, reviewers may request that you complete any actions in this list if you
 
 - [ ] My PR is **created against the `main` branch** of code (unless it is a backport or is fixing an issue specific to an older branch).
 - [ ] My PR is **small in size** (e.g. less than 1,000 lines of code, not including comments & specs/tests), or I have provided reasons as to why that's not possible.
+- [ ] My PR **follows all coding best practices** based on the [Code Conventions Guide](../CODE_CONVENTIONS.md)
 - [ ] My PR **passes [ESLint](https://eslint.org/)** validation using `npm run lint`
 - [ ] My PR **doesn't introduce circular dependencies** (verified via `npm run check-circ-deps`)
 - [ ] My PR **includes [TypeDoc](https://typedoc.org/) comments** for _all new (or modified) public methods and classes_. It also includes TypeDoc for large or complex private methods.
 - [ ] My PR **passes all specs/tests and includes new/updated specs or tests** based on the [Code Testing Guide](https://wiki.lyrasis.org/display/DSPACE/Code+Testing+Guide).
-- [ ] My PR **aligns with [Accessibility guidelines](https://wiki.lyrasis.org/display/DSDOC9x/Accessibility)** if it makes changes to the user interface.
+- [ ] My PR **aligns with [Accessibility guidelines](https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408944958/Accessibility)** if it makes changes to the user interface.
 - [ ] My PR **uses i18n (internationalization) keys** instead of hardcoded English text, to allow for translations.
 - [ ] My PR **includes details on how to test it**. I've provided clear instructions to reviewers on how to successfully test this fix or feature.
 - [ ] If my PR includes new libraries/dependencies (in `package.json`), I've made sure their licenses align with the [DSpace BSD License](https://github.com/DSpace/DSpace/blob/main/LICENSE) based on the [Licensing of Contributions](https://wiki.lyrasis.org/display/DSPACE/Code+Contribution+Guidelines#CodeContributionGuidelines-LicensingofContributions) documentation.

CODE_CONVENTIONS.md

@@ -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).
+
+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. 

CODE_STYLE.md

@@ -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.

CONTRIBUTING.md

@@ -12,18 +12,10 @@ DSpace is a community built and supported project. We do not have a centralized
 We accept [GitHub Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) at any time from anyone.
 Contributors to each release are recognized in our [Release Notes](https://wiki.lyrasis.org/display/DSDOC9x/Release+Notes).
 
-Code Contribution Checklist
-- [ ] PRs _should_ be smaller in size (ideally less than 1,000 lines of code, not including comments & tests)
-- [ ] PRs **must** pass [ESLint](https://eslint.org/) validation using `yarn lint`
-- [ ] PRs **must** not introduce circular dependencies (verified via `yarn check-circ-deps`)
-- [ ] PRs **must** include [TypeDoc](https://typedoc.org/) comments for _all new (or modified) public methods and classes_. Large or complex private methods should also have TypeDoc.
-- [ ] PRs **must** pass all automated pecs/tests and includes new/updated specs or tests based on the [Code Testing Guide](https://wiki.lyrasis.org/display/DSPACE/Code+Testing+Guide).
-- [ ] User interface changes **must** align with [Accessibility guidelines](https://wiki.lyrasis.org/display/DSDOC9x/Accessibility)
-- [ ] PRs **must** use i18n (internationalization) keys instead of hardcoded English text, to allow for translations.
-- [ ] Details on how to test the PR **must** be provided. Reviewers must be aware of any steps they need to take to successfully test your fix or feature.
-- [ ] If a PR includes new libraries/dependencies (in `package.json`), then their software licenses **must** align with the [DSpace BSD License](https://github.com/DSpace/dspace-angular/blob/main/LICENSE) based on the [Licensing of Contributions](https://wiki.lyrasis.org/display/DSPACE/Code+Contribution+Guidelines#CodeContributionGuidelines-LicensingofContributions) documentation.
-- [ ] Basic technical documentation _should_ be provided for any new features or configuration, either in the PR itself or in the DSpace Wiki documentation.
-- [ ] If a PR fixes an issue ticket, please [link them together](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+We provide a [Code Contribution Checklist in our Pull Request Template](https://github.com/DSpace/dspace-angular/blob/main/.github/pull_request_template.md#checklist) which includes guidance
+on things we will look for in your PR.
+
+We also provide a [Code Style Guide](CODE_STYLE.md) (detailing how to format your code) and a [Code Conventions Guide](CODE_CONVENTIONS.md) (detailing established coding best practices).
 
 Additional details on the code contribution process can be found in our [Code Contribution Guidelines](https://wiki.lyrasis.org/display/DSPACE/Code+Contribution+Guidelines)
 
@@ -37,7 +29,7 @@ Once you have an account setup, contact @tdonohue (via [Slack](https://wiki.lyra
 ## Help others on mailing lists or Slack
 
 DSpace has our own [Slack](https://wiki.lyrasis.org/display/DSPACE/Slack) community and [Mailing Lists](https://wiki.lyrasis.org/display/DSPACE/Mailing+Lists) where discussions take place and questions are answered.
-Anyone is welcome to join and help others. We just ask you to follow our [Code of Conduct](https://www.lyrasis.org/about/Pages/Code-of-Conduct.aspx) (adopted via Lyrasis).
+Anyone is welcome to join and help others. We just ask you to follow our [Code of Conduct](https://lyrasis.org/code-of-conduct/) (adopted via Lyrasis).
 
 ## Join a working or interest group
 

README.md

@@ -10,7 +10,7 @@ Overview
 
 DSpace open source software is a turnkey repository application used by more than
 2,000 organizations and institutions worldwide to provide durable access to digital resources.
-For more information, visit https://www.dspace.org/
+For more information, visit https://dspace.org/
 
 DSpace consists of both a Java-based backend and an Angular-based frontend.
 
@@ -24,13 +24,15 @@ Downloads
 * Backend (REST API): https://github.com/DSpace/DSpace/releases
 * Frontend (User Interface): https://github.com/DSpace/dspace-angular/releases
 
+On our wiki, you may also find a [list of all past releases, including their current levels of support](https://wiki.lyrasis.org/spaces/DSPACE/pages/69010426/Releases).
+
 
 ## Documentation / Installation
 
 Documentation for each release may be viewed online or downloaded via our [Documentation Wiki](https://wiki.lyrasis.org/display/DSDOC/).
 
 The latest DSpace Installation instructions are available at:
-https://wiki.lyrasis.org/display/DSDOC9x/Installing+DSpace
+https://wiki.lyrasis.org/display/DSDOC10x/Installing+DSpace
 
 Quick start
 -----------
@@ -349,7 +351,7 @@ See our [DSpace Code Testing Guide](https://wiki.lyrasis.org/display/DSPACE/Code
 Documentation
 --------------
 
-Official DSpace documentation is available in the DSpace wiki at https://wiki.lyrasis.org/display/DSDOC9x/
+Official DSpace documentation is available in the DSpace wiki at https://wiki.lyrasis.org/display/DSDOC10x/
 
 Some UI specific configuration documentation is also found in the [`./docs`](docs) folder of this codebase.
 
@@ -382,7 +384,11 @@ To get the most out of TypeScript, you'll need a TypeScript-aware editor. We've
 Contributing
 -------------
 
-See [Contributing documentation](CONTRIBUTING.md)
+See our [Contributing guidelines](CONTRIBUTING.md) for general tips on contributing back to DSpace.
+
+For developers, we also provide guidelines for:
+* [Code Style](CODE_STYLE.md) - our code formatting rules
+* [Code Conventions](CODE_CONVENTIONS.md) - our established coding best practices
 
 File Structure
 --------------
@@ -564,7 +570,7 @@ DSpace uses GitHub to track issues:
 License
 -------
 DSpace source code is freely available under a standard [BSD 3-Clause license](https://opensource.org/licenses/BSD-3-Clause).
-The full license is available in the [LICENSE](LICENSE) file or online at https://www.dspace.org/license/
+The full license is available in the [LICENSE](LICENSE) file or online at https://dspace.org/license/
 
 DSpace uses third-party libraries which may be distributed under different licenses. Those licenses are listed
 in the [LICENSES_THIRD_PARTY](LICENSES_THIRD_PARTY) file.