Components/tooling choices

[pimotte]

This is a non-exhaustive list of components and tooling we could use to improve maintainability and sustainability of discipl libraries, organized per topic in suggested rough order of priority. Feel free to edit this post/add remarks in comments.

Libraries and Applications:

• Test framework (WIP: ES6 and testing framework #13, Testing: mocked and memory #14)
• Continuous Integration (Adding Continuous Integration #9)
• Style guide (and linter) (Adding standard linter #16)
• Documentation (WIP: Documentation: jsdoc2markdown within GitHub #21)
• Code coverage (Adding code coverage #17)
• Badges
• Quality Gate (a19e428, Improve Sonar integrations #19)
• Publishing to npm (and using semver)
• Contributor Guidelines

Applications:

• i18n
• Containerization
• end-to-end tests

Test Framework

Possibilities:

• Jasmine
• Mocha+Chai

In both cases Karma is the de-facto test runner used by many projects.

Mocha+Chai has been chosen for flexibility.

Continuous Integration

Travis has solid support for GitHub and open source projects. #9 shows how it could be added.
I've heard good things about Circle CI, which offers 4 free concurrent builds for open source projects. GitLab CI/CD is also a possibility (even without using GitLab for code hosting)

Style guide and linter

There are a couple of alternatives out there, main ones being AirBnB, Google and standard. The AirBnB one starts with "this guide assumes you're using babel", which we are not at library level. Between Google and standard, standard seems to have a lot of nice integrations, and is low-config, with the possibility to eject to an eslint config if we decide we want to customize rules.

Documentation

There are some JSDoc comments, which could be used to auto-generate documentation. Given how long the README is, a "Content" section with anchor links probably wouldn't hurt.

Options:

• Use JSDoc (generates HTML)
  • Host through GitHub Pages
  • Host independently from GitHub (i.e. discipl.org)
• Use jsdoc-to-markdown
  • Host raw from repo (i.e. link to the file, which will be rendered in GitHub)
  • Host with GitHub Pages
  • Embed in a bigger site, hosted independently from GitHub (using e.g. GitBook)

Code coverage

Karma as a test runner can provide code coverage using istanbul. The only alternative to istanbul I could find was c8, which uses coverage exposed by the v8 engine. This does require the latest version of node, and might require some engineering to get working with a test runner.

Badges

More of a thing per topic, actually. More or less every other component on this list could have a badge. Essential would be CI and coverage badges. Style/linter, quality and an npm badge are also possible.

Quality gate

SonarCloud offers free quality checks for open source projects. I'm not aware of a suitable alternative.

Npm and semver

Currently a lot of the components are referenced using git-links. This is probably doable for now, but not sustainable in the long run. Publishing to npm does add some overhead, but allows clearer versioning and allows others to easily start using discipl.

With respect to semver, I propose to use 0.x.y for now. I have also seen projects where the minor version is then used for breaking changes and the patch version is used for non-breaking changes, even though this is not required by semver.

Contributor guidelines

Not of the highest priority right now. Items that could contribute to this are: Code of Conduct, Issue and/or Pull Request templates.

i18n

Specific technologies would depend on choice of frameworks.

Containerization

Docker. Using multi-stage builds is a good way to containerize the build process while also obtaining a slim deliverable.

End to end tests

Specific technologies would depend on choice of frameworks

[sgort]

Hi Pim, thanks for your contribution. appreciate your proposal and will ask my network to comment on this and / or contribute to it.

[sgort]

Via Milo van der Linden:

Read the proposal. It's a solid toolchain proposal in my opinion. The only thing I want to add is: use containers; loosely coupled, Docker file in every repo, well documented. And any frontend should have i18n from the start.

[bkaptijn]

Mocha+Chai+Sinon more flexible than Jasmine. I'd rather go with that for now I guess.

[bkaptijn]

Enabled travis for CI for now.

[bkaptijn]

Also added CI badge

[pimotte]

Mocha+Chai+Sinon more flexible than Jasmine. I'd rather go with that for now I guess.

A colleague of mine also suggested that the Mocha-stack was more modern, so I'm totally good with this.

[pimotte]

Via Milo van der Linden:

Read the proposal. It's a solid toolchain proposal in my opinion. The only thing I want to add is: use containers; loosely coupled, Docker file in every repo, well documented. And any frontend should have i18n from the start.

Added these to main post along with end to end testing.

[bkaptijn]

Let's use standardjs

Let's try to use karma/instanbull

The documentation contains a main introduction on Discipl, which should not be in this project. I'll add a new main to contain this common README and probably could contain other common stuff (like this issue actually). Will look at improving the documentation / autogenerating parts of it and as much as badges as is nice to have.

agree about npm / semver. was already going this way: https://www.npmjs.com/package/discipl-core latest published one is version 0.3.3

Ok, started with sonarcloud:
https://sonarcloud.io/organizations/discipl/projects
Still have to configure it / integrate it with travis

i18n : meerdere opties beschikbaar van kleine modules tot meer full featured: https://www.i18next.com , globalizejs.com . Nog meer opties?

[pimotte]

Regarding i18n, I'd say it depends on the application, and frameworks? I think it makes sense to use something like this for react native. Not sure if we have other situations where localization is prudent?

[pimotte]

Also, regarding npm, would we like to claim the scope @discipl and publish packages there?

Advantage is that we clearly signal which are our packages. We would have to refactor the dynamic import though.

[bkaptijn]

Claiming scope @discipl seems a good thing to do yes.

[bkaptijn]

short: I think we agree.

Most platforms make claims referenceable through some id of which you can be sure it leads to the claim you want to reference.

Some platforms may not be able or explicitely do not do this however.. but as said, i think it is better to have these connectors implement themselves how to reference a claim in that case implying it can differ per platform and you'll always need the platform connector to be able to interpret the reference, but i don't see the problem in this.

I guess in any case, the connector itself returns an id, whether it is a pure reference or one with semantic meaning or even a json object. The discipl core api just transforms this in a string with
a did like link format (link:discipl:-) .. the id here being json stringified and base64 encoded to make it robust..

the length should be limited reasonably too though i guess.. though platforms that have to store the link can choose to hash the id in the link themselves too to shorten it, if it is ok to do so given it's use...

Also note #8 (about the did v0.11 compliancy) .. though this is already taken into account probably too if we do things as described above.

[pimotte]

short: I think we agree.
...

I think this comment is meant for #5 ?

[pimotte]

I have listed some documentation options in the first comment and executed the one with the least dev effort at #21