However we don't want to make unit tests a hard requirement to be able to commit anything. But there have to be tests before it can be merged in to master
We can always relax that policy if it proves to be too restrictive
End to end test shouldn't be required but should be encouraged
Jasmine, protractor and karma are fine
i18n
Description
Angular 2.0.1 added a first version an i18n system, however it’s still tagged as experimental and that shows.
It’s not easy to work with
your translations files have to be generated from the templates using a tool. If you add fields afterwards, you have to generate it again, and merge the already translated messages in
It doesn’t seem to support variables
and doesn’t support language switching at runtime.
It creates a version of the entire app in every language and you need to go to the one in the language you’d like.
Conclusions
we'll stick to ng2-translate for now, which is the third party module we used in the prototype, as it doesn’t have all these downsides.
CSS
Description
Framework
Angular material still has multiple downsides
lacks a number of components
lacks customisability
lacks basics we need, like a grid system
Bootstrap 4 while in alpha seems like a better choice
Do we want to use component styles or not?
while that has the advantages
that your style is highly modular
that component styles can’t influence or break each other
How will that work in respect to theming?
will that require someone writing a theme to modify the component CSS for every component?
Component styles shouldn't be a problem for themablity as global, overriding styles can be added using the view encapsulation property of the app component
So we'll use component styles
Storing state & Data Abstraction Layer
Description
In order to end up with a robust system, with good performance, that's easily testable and minimizes the risk of unexpected side effects, we want to avoid leaving the implementation of calls to the backend, and the storage of state up to the individual developer of a component or service.
To manage state in the application we could look towards Redux, and ngrx
For a structured data abstraction layer JS Data is worth investigating
Both of these could be used separately or together.
While they have many advantages, they'll also make it more difficult for new developers to get involved. Is the extra structure worth it?
Conclusions
There is also universal storage, part of angular universal that has some overlap
Not enough people have experience with redux, js data or universal storage.
We will research this by the next meeting, in order to come to an informed decision.
UI Style Guide
Description
Should we create a document that describes how the UI should work, what it's components are, how they should be designed, what is customizable in the theme, etc.
Do we create one single theme, or a version that is a blank slate, and an opinionated version that showcases what can be achieved
Do we make (part of) this before development can start?
Conclusions
In order to achieve a cohesive design it's important to start formalizing these things early on
We need a first draft during the initial stages of development, and adjust it later on if necessary
We should focus on a "blank slate" theme first, as it will be easier to create an opinionated version started from that as the other way around
Afterwards create the opinionated theme
Misc
Description
Are we going to require that code be documented using TypeDoc as in the prototype?
Will we use a code style guide?
How do we decide and communicate about the use of a new 3d party library or component?
Do we put resources on the Duraspace or github wiki?
We could remove the concept of communities from the UI, and use the term collection for everything, even if nothing changes to the backend. Is dat something we want to do?
it would bring DSpace in line with PCDM
Conclusions
We'll ask everybody to use TypeDoc
We'll use the standard angular code style guide as a starting point, deviations from it can be added later on.
If you want to introduce a new 3d party dependency you should bring it up in these meetings
We'll put everything on the Duraspace wiki, but will add a summary to the README.md file on github
We'll remove the concept of communities from the UI. However we should take care not to introduce too many changes in DSpace 7 to keep the workload under control.
Detailed note for the new REST API meeting (2nd hour)
REST API Contract
We agree about the opportunity to base our work on a clear contract document to enable the Angular 2 team to work on mockup services and provide early feedback without the need to wait for a full implementation on our side. We have discussed about the best way to share the documentation and receive feedback and we have agreed to stay as much as possible close to the official DSpace channels to keep all the community involved. Concretely this mean that:
discussion will happen on the dspace-devel mailing list
source code will be hosted in the official DSpace repository on the master branch (DSpace 7)
a new maven webapp will be introduced to build the new REST API
the contract will be maintained if possible on the dspace wiki, the decision about which framework to use to build the REST API could lead to a difference prefer as a static website build on a github doc repository (see point Spring Documentation REST project)
As good example of well documented REST API contract we will look to
provide the list of accepted methods and their meaning for all the endpoints
provide the details about the request format expect as input for all the endpoints with samples
provide the details about the response format for all the endpoints with samples
provide details about response code, and error codes for all the endpoints
Backward compatibility
We discussed about the need to guarantee compatibility across new version of the REST API both in regards to DSpace 6 vs DSpace 7 than DSpace 7 vs DSpace 7+. The general agreement was to keep in place support for the DSpace 6 REST API for at least 1 version (so in some way deprecate the current REST API in DSpace 7) as a separate webapp build out-of-box in DSpace 7.
The new REST API should be structured in a way that new version are additive in information and functionalities so that the impact on the client is minimal and, when the client is properly programmed ignoring unknown information, new version of the new REST API are fully backward compatible.
Design decision
We agree to implement support for the HateOAS paradigm. We need to take a decision about the specific hypermedia format to use to keep the new API consistent and easy to use by client developers. Candidates are as follow
HAL is supported out-of-box by the Spring Data REST project that looks as one of the most interesting framework to use to build the new REST API. JSONAPI looks as the most advanced standard and it is originated by the ember community.
Framework to evaluate
We want to keep the development of DSpace as effective and sustainable as possible. To do that we need to pick technologies and framework that play nicely together with no or minimal effort from the DSpace developers (focus on developing DSpace not the framework) in this regards we are looking to the solution provided in the Spring family
Spring Data Rest - http://projects.spring.io/spring-data-rest/ It allows to build almost automatically REST API from Spring Data Repository. It provides configuration options to customize the resulting REST endpoints, parameters and provide support for API discovery (Application Level Description) and profile (how much details and information include in a specific response with client negotiation - profile)
Spring REST Documentation - https://projects.spring.io/spring-restdocs/ It allows to build the REST contract using test. This will guarantee a good test coverage other than accurate and easy to maintein documentation as it will be close to the source code
the possibility to merge community and collection: we agree to keep a look to this option, the Angular 2 UI team will start to design an UI where there is not difference between Community and Collection. We need to check how much complex is to really remove such difference in the data model or at least hide such difference behind the REST API (i.e. have a single endpoint that will talk with both communities & collections). We agree that this is not a primary goal for the project and it will be delayed if it cannot be accomplished with minimal effort
to simplify the packaging of DSpace ending up in a single webapp including all the supported modules SWORD, SWORDv2, RDF, OAI. Servlet 3 and web-fragment could be a good way to achieve that and also allow extension of the new REST API / single webapp in a pluggable way. We agree that this is not a primary goal for the project and it will be delayed if it cannot be accomplished with minimal effort
authentication & authorization. We want to explore the use of Spring Security to simplify both aspects of the DSpace architecture
Next steps
Make experiments with the proposed frameworks
Some PRs should be prepared to
add a new (almost empty) web application to hold the new REST API code
remove the JSPUI and XMLUI maven project from the DSpace github repository moving them to dedicated backup repositories under the DSpace organisation
Prepare an exhaustive list of functionalities that need to be exposed over the REST API staring from the need for the next Angular 2 UI milestone (Browse)
List current known limitation of the DSpace REST API