Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
Quick Links
- The source code can be found on github: https://github.com/DSpace/dspace-angular
- There's a project board on waffle.io: https://waffle.io/DSpace/dspace-angular
Developer Resources
- Overview of the new Technology
- Official Angular2 for TypeScript Style Guide
- RxJS - creating new sequences or using existing sequences
- DSpace Wiki: TypeScript-Guideline
Contributors
- Art Lowel (Atmire)
- William Welling
- James Silas Creel
- Tim Donohue
- Matteo Perelli
- Giuseppe Digilio
- Martin Walk
How to contribute
Prerequisites
- You'll need to be in the dspace-angular github team to get the required access. Send your github username to Art Lowel (Atmire) to get an invite.
- Fork the repository on Github
- Refer to DSpace 7 UI Technology Stack for learning resources about the technologies used.
Workflow
Have a look at the project board
Take an issue that’s in the ready section and has nobody assigned to it
assign yourself
When you start working on it, move the issue to the “in progress” section
Work on a separate branch for the issue on your fork
- When you’re ready, fire a pull request
in the comments of the pull request, write something akin to “this PR connect’s to #{the ID of the issue}”. That way the issue will be moved automatically to the review column.
When at least two people have reviewed and approved your PR, it can be merged in master.
You can also help out by reviewing the pull requests of other people
Please keep an eye on your pull request afterwards, the reviewers may have questions or comments about it, or ask you to tackle things in a different way, before they can approve it
Most discussions about the task or the pull request can happen through the github & project board comments.
If it’s more complex you can bring it up in one of these meetings.
After your Pull Request has been merged, drag the issue to the done column on the project board. (this can also be automated by adding “this merge closes #{the id of the issue}” in the merge comment.
Guidelines
Code Style
- Follow the official angular 2 style guide. It contains guidelines for naming files, directory structure, etc.
- TSLint can help you with that. It will run automatically whenever the code is rebuilt (even during a watch task) or you can run it manually with
npm run lint
Documentation
- Document your code in the TypeDoc format
Testing
- Write tests for your code. We use jasmine for unit testing and protractor for end-to-end.
- Ensure your code doesn't break any existing tests.
(S)CSS
- General
- Avoid writing (S)CSS if you can. Instead use Bootstrap 4 CSS classes and components where possible. That way it will be much easier to keep the style consistent across many different contributors.
- If you want to use a bootstrap component, take a look at the ng-bootstrap docs first. Chances are they've already turned it into an angular component for you.
- If you need to add margins, padding, change font-sizes or colors etc, make use of the bootstrap variables rather than entering numerical values. (e.g. write
margin-bottom: $spacer-y;
instead ofmargin-bottom: 15px;
andcolor
instead of: $brand-primary;
color: #0275d8;
- If there's no other way but to add a numerical value or color code yourself, consider turning it in to a variable, so it can be reused by others. Also calculations that are used more than once can benefit from being stored as variables: e.g.
$ds-table-margin-bottom: ($font-size-base * 2) - ($gutter-width / 2);
Component Styles
- Angular 2 makes use of component styles. By default, these can't leak out and affect the style of other components. Not even child components
- The style for a component should go in a file called
name.component.scss
, in the same directory as the component. e.g. forsrc/app/home/home.component.ts
the component style file issrc/app/home/home.component.scss
. - Note that the
styleUrls
parameter of the component refers to a CSS file, not an SCSS file. That's because the AoT build process doesn't yet support SCSS, and the SCSS files get converted to CSS ahead of time. More information in the comments on this PR.
i18n
- Don't hard code user-facing text in components. We're using ng2-translate for i18n. You use it by adding your key to resources/i18n/en.json, and then using that key in the component with the
translate
pipe. e.g.:- in en.json put:
"my-route.my-component.my-label-descriptor": "My User Facing Text";
- in your component put:
"<h1>{{ 'my-route.my-component.my-label-descriptor' | translate }}</h1>"
- in en.json put:
- For more info see the ng2-translate docs
General
- Keep adaptability in mind. An institution installing DSpace will often want to modify a few things about the UI. The easier we can make that, the better. Therefore keep your components small (divide them in to sub-components), make sub-modules for coherent functionality, use SASS variables, etc.
- We agreed to remove the concept of Communities from the UI. They should be called Collections as well.