Release roadmap - Githubissues

dherges commented 7 years ago

Hi everyone,

as you noticed in the develop branch of this repo, there is some work going on as of late. I'd like to give you my views on plans and ideas with ng-hal. Feel free to give your feedback and thoughts. Your input is very much appreciated since you are the users of this library. Also, since switching my employer there is more space and time for open-source 🌟

Features

AoT support: from now on, the library will be compiled through ngc, making it available to be used with Ahead-of-Time compilation. manekinekko/angular-library-starter has been a source of inspiration.
API design
- HAL: entities represented in the HAL specs will be centered around Resource, Link, LinkCollection, and ResourceCollection. The public API of this library will no longer expose typings of halfred directly. However, the type definitions of halfred and this library are designed to be type-compatible for the time being.
- URI Templates: entities represented in RFC 6570 are reflected in the Uri class. Also, the dependency on uri-templates is removed and ng-hal will provide an implementation of its own.
Testing & Test Coverage
- this is something that needs to be improved. I'd like to verify two core parts of the library: 1) normalization of JSON documents, representation through Resource & co. – right now, this task is delegated to halfred. Verifying that behaviour gives the chance to make changes to these parts in the future. 2) verifying the behaviour and API of Navigator with mocked http responses. This will be more like integration testing the most common use cases.
- there is no discrete threshold for test coverage. Classes like Navigator, Resource, Link, Uri, and so so on should reach as much coverage as possible (e.g. in the 90s area 🚀 )

Versioning

I'd like to push out this library in a stable version asap. However, there is no schedule.

Since the Angular team is pushing really hard on new versions, this library should support both Angular versions 2.x and 4.x. The aim is to have one API that works on both Angular versions, making the library available for as many users as possible. The versioning scheme for ng-hal will look like this:

ng-hal@2.x.y: released for, tested, and built against angular@^2.0.0
ng-hal@4.x.y: released for, tested, and built against angular@^4.0.0

The transitioning phase will include frequent releases of 0.x.y versions. In this phase, the API may change frequently and heavily. If you have ideas and wishes, please provide them during this phase. As soon as the API has stabilized and a sufficient test coverage has been met, ng-hal will be released as 2.0.0 and 4.0.0 at the same time. Subsequent releases will come in tandem, e.g. 2.1.0 and 4.1.0 released at the same time, as will 2.2.2 and 4.2.2, and so on.

Again, if you have any ideas or wishes, please let me know! ⛱

patrickmichalina commented 7 years ago

Have a timeline in mind for when these new changes will be released? AoT is not working at the moment as well as another bug relating to emitHelpers (__extend keyword).

dherges commented 7 years ago

Hi @patrickmichalina,

there's no real timeline or schedule for when it will be 1.0.0. It's largely down to a stable API, yet I don't know when that will be.

To make the latest changes in develop available (which includes AoT support), I just published an 0.4.0 to npm. You can try it out now.

patrickmichalina commented 7 years ago

@dherges thanks for pushing this out! But unfortunately this is not going to work in the current form. SystemJS does not recognize the paths to the subfolders like './conversations' since SystemJS does not default to adding 'index.js' like other loaders do. I would recommend getting rid of barrels and/or loading explicit paths. You could also consider packaging a UMD to help with some of these various loader issues.

dherges commented 7 years ago

@patrickmichalina oh. my. gosh.

I'm still learning that distributing an angular library is more complex than developing an app.

Do you have any resources or articles showing how-to build a library? Is it ngc to es2015 + metadata w/o factories and ngsummary -> rollup to iife -> tsc to es5, finished. Is it that? Is there more?

-- edit alternative, ngm could be sufficient. I'll have a closer look at these things in the coming week...

patrickmichalina commented 7 years ago

Yea - it is super complicated these days!

I would recommend using this as a harness for the project: https://github.com/mgechev/angular-seed

It isn't made for library development in particular, but you can add tasks to distribute the library. It also has the benefit of creating an example app to show the system in use.

dherges commented 7 years ago

relates to angular/angular-cli#1692

izub commented 7 years ago

Any idea when a release with Angular 4 support will be made? Currently ng-hal is the only package blocking me from updating to the new version.

dherges commented 7 years ago

@izub no, sorry. what's blocking is the "get rid of halfred"-thing. since it's a full-spare-time side project, i rarely find concentration to work here. this weekend will be no time. hoping for next week...

Do you have any issues with the lib in Angular4 except the "unmet peer dependency" warning during npm install?

izub commented 7 years ago

@dherges I haven't tested this yet, but I guess it's only the "unmet peer dependency" warning.

Would it be possible to do a quick patch 0.x release just to update the @angular dependencies? Or set a version constraint which supports both? (^2.4.10 || ^4.0.0) It's quite likely none of the (breaking) changes of 4.0 have impact on the ng-hal codebase.

dherges commented 7 years ago

@izub can you check whether changes in 4126e8288a558508632af301dd20320cb900d0f9 will satisfy your needs?

You can install with "ng-hal": "https://github.com/dherges/ng-hal.git#feat/ng-2-and-4-release" in dependencies.

izub commented 7 years ago

@dherges Those changes look like they should be satisfactory.

Unfortunately when updating the dependency in my package.json to "ng-hal": "https://github.com/dherges/ng-hal.git#feat/ng-2-and-4-release" and doing an npm install (even a complete re-install of all packages) does not install anything related to ng-hal at all.

When trying to update the dependency via npm install https://github.com/dherges/ng-hal.git#feat/ng-2-and-4-release --save, it will add a "ng-hal-demo": "git+https://github.com/dherges/ng-hal.git#feat/ng-2-and-4-release" entry to my package.json.

When looking at the feat/ng-2-and-4-release and the develop branch, these seem to have a quite different structure as well compared to the 0.4.0 branch (I can't seem to find the 0.4.1 branch).

But regardless of that, I've tested ng-hal 0.4.1, ignoring the "unmet peer dependency" warning and everything seems to be working without any issues.

dherges commented 7 years ago

@izub yes,sure, the npm package is assembled in dist/ng-hal

A 0.4.2 release is prepared and ready to be published in release/v.0.4.2. It will be out on npm registry as soon as I get back to my private place (~wednesday 26th april evening).

dherges commented 7 years ago

You are going to kill me, guys. As you see ... ng-hal is not used at my current work place in production and so it is a 100% side project ("U-Boot-Projekt" as we call it) which is sometimes going a little further and sometimes going backwards but sometimes nothing happens.

With Angular 5, it would make sense to switch to HttpClient instead of the "old" Http API. Also, when brainstorming lately, we found out that a "fluent CSS-selector" API would be cool for traversing HAL documents – very much like protractor or selenium do for selecting DOM elements from a web page.

this.http.post(linksFrom(foo).rel('bar'), resourceFrom({}).withSelfHref('foo/bar') )

const foo = { _links: { self: { href: 'foo/bar' } } };
resourceFrom({}).withSelfRel(foo));

resourceFrom({}).withRel('next', 'foo/bar'));
resourceFrom({}).withRel('next', { href: 'foo/{bar}', templated: true } ));

There are a few ideas how to leverage HAL for "fluent" Angular clients ... but nothing "soon to be production-ready" here. If you are using this on production, I'd honestly recommend to maintain your fork of this repo or copy-paste code from here and built for your own needs.

dherges commented 7 years ago

Here are the drafts and sketches for a fluent API in Navigator (class may be renamed to HalClient?)

Basic idea is to .post({}), .put({}), .get({}) resource objects as well as .post('/url') (and so on...)

dherges commented 7 years ago

With the HttpClient and the declaration overloading, another idea is to map the rel semantics to a data structure, e.g.:

rel=animals maps to interface Animal {}

and the method name to a "stub" implementation of the media type:

.collection(...) maps to CollectionResourceApi

and CollectionResourceApi would implement the protocol for that media type like

  findAll(page?: number, size?: number, sort: SortCriteria[]);
  createOne(entity: T)

so that:

api.collection('animals')
  .switchMap((animals) => {
    /* animals: typeof CollectionResourceApi<Animal> */
    const page = 2;
    const size = 6;
    const sortByName = {propertyName: 'name', direction: 'asc' };
    return animals.findAll(page, size, [ sortByName ]);
  })
  .subscribe((res) => {
    /* res: typeof CollectionResource<Animal> */
    const animals = res._embedded.items; // Animal[]
    console.log(`There are ${res.page.size} animals!`);
  });

A draft code can be found somewhere else:

https://github.com/dherges/dgeni-ngx/blob/master/sample/src/app/hal-api/hal-api.service.spec.ts#L34-L38

jonyeezs commented 6 years ago

The state of master seems to be broken.

There are alot of missing dependencies/references. So much has changes in the current version. Whole infrastructure.

eg: https://github.com/ng-hal/ng-hal/commit/cacfdba8b3b16b178ba60c57d1187d683b0f8e49

It seems to be incomplete, few things remove but not replaced. The way the library is structured has also changed.

There is no PR or roadmap to indicate the goal of the new path taken.

@dherges could you help shed some light what is your goal in mind with the overhaul so other contributors can help carry on your good work.

Thanks!

ng-hal / ng-hal

Release roadmap #6

Features

Versioning