Shields: Update tutorial for new service architecture

[chris48s]

Tutorial should cover how to write a service that extends BaseService/BaseJsonService

[paulmelnikow]

@niccokunzmann who wrote the original tutorial has offered to help with this!

Any thoughts on how the work could be divided?

[chris48s]

OK. Having a quick scan over the docs, the testing docs also need some work. Maybe as a starting point, one of us can take the tutorial and the other one can do the service test docs? Code review provides an opportunity to check we're covering everything. @niccokunzmann - are you most keen to work on the tutorial? The perspective of someone who is a bit further removed might be really valuable here. If so I will take the test docs.

The most important first step is to get the tutorial to a stage where the docs reflect reality. Maybe we don't have to cover all of these for an opening gambit, but I do have a few topics in mind that we should cover in the docs:

• fetch()/render() pattern
• Contract by design, writing a validator
• When to use static/instance methods
• Available helper functions in /lib (maybe this is its own docs section to cover properly, but we should touch on this in the tutorial)
• Inheritance/service 'families'
• Static examples

do you have anything else in mind that should go on that list @paulmelnikow ?

I'll probably also take the opportunity to read over the rest of the docs and see if there's anything else that needs a 'refresh' :)

[niccokunzmann]

From my perspective there is not "one" tutorial. We have these service families:

• JSON
• raw data
• in the future possibly also XML (I think, it works like the JSON one with XML to JSON conversion)

So, the tutorial would best cover what is most needed and common to all of them first. Then, there are differences, each getting a sub-chapter. I like complete code examples that would work if you copy them in. Is there a service which would be good to take as an example from your point of view?

[chris48s]

In principle I agree with that. In reality, I think all of the services we currently have an example of extend BaseJsonService, so I'd be happy to start off with that and we can evolve the docs as we port more badges that do something different.

Just to be really clear on this: are you going to work on TUTORIAL.md ?

[niccokunzmann]

Just to be really clear on this: are you going to work on |TUTORIAL.md| ?

As long as I do not create a pull request, consider it a no. I can not
truthfully make a promise to you as I do not know you enough.
I am undecided at the moment and cannot tell for the coming days.
If you write something, I may still come in again, so do not wait for me.

[chris48s]

OK cheers. I will aim to work on updating the tutorial myself in the next few days. Feel free to contribute your thoughts either in review or at a later date. Documentation can always be extended and improved over time.

[paulmelnikow]

Two things come to mind:

• An overview of the design: in a few sentences, how does the service work? How does a service get registered, executed, tested? How is the frontend generated? Try to take the magic out of it.
• Advice on porting existing services, and on refactoring

And a third, though it's not about the service rewrite:

• A description of our code review process

[chris48s]

tutorial updated in https://github.com/badges/shields/pull/2042

Next jobs:

• Update/refresh the service testing docs
• Add docs on how to port legacy services

I think I'm going to defer adding the docs on service families just now given the discussion we're having in https://github.com/badges/shields/pull/2031 given we may want to change the advised way of doing this.

[techtonik]

Add docs on how to port legacy services

I am very much interested to read these docs for https://github.com/badges/shields/issues/2420. =) Maybe start with TUTORIAL.md will be enough.

[paulmelnikow]

I drafted some quick ones: #2429.

[paulmelnikow]

Think this can be closed?