AsyncAPI Hacktoberfest, 30 Sep 2020

Previous Meeting

⏯

youtube image

►

From YouTube: How To Find The Right Issue To Work On And What Are They About | Hacktoberfest

Description

This video explains what issues we prepared for you at AsyncAPI Initiative for the Hacktoberfest. We also explain here the issues that are more complex.

0:00 Intro
0:49 Explanation of issues difficulty levels
3:42 https://github.com/asyncapi/generator/issues/399
5:33 https://github.com/asyncapi/html-template/issues/15
8:28 https://github.com/asyncapi/html-template/issues/24
11:17 https://github.com/asyncapi/html-template/issues/26
12:05 https://github.com/asyncapi/html-template/issues/50
13:34 https://github.com/asyncapi/html-template/issues/69
14:38 https://github.com/asyncapi/html-template/issues/71
16:40 https://github.com/asyncapi/html-template/issues/72
18:30 https://github.com/asyncapi/html-template/issues/78
21:05 https://github.com/asyncapi/nodejs-template/issues/4
22:18 https://github.com/asyncapi/nodejs-template/issues/8
25:28 https://github.com/asyncapi/parser-js/issues/100
27:29 https://github.com/asyncapi/parser-js/issues/140
28:43 https://github.com/asyncapi/parser-js/issues/142
30:07 https://github.com/asyncapi/parser-js/issues/145
30:56 https://github.com/asyncapi/parser-js/issues/157
33:16 https://github.com/asyncapi/parser-js/issues/164
34:20 https://github.com/asyncapi/parser-js/issues/173
37:27 Closing words

For more details read this blog post - https://www.asyncapi.com/blog/hacktoberfest-2020

A

Hey in this video you're going to learn what kind of issues we prepared for you for the oktoberfest, so first of all, we've put all the issues in a in a sheet where you can not only learn. What's the link to the issue, but also some additional metadata information uh that will help you out to understand uh what you will work on. So, first of all, we try to identify the area that is covered by a given issue.

A

So there's a lot of coding with javascript.

A

There are docs that you can work on even a few issues about css and html and there's a lot of ci in here and if it comes to ci configuration, it's always github actions. Now. Another information you can get from this sheet is um level of difficulty.

A

When we were assigning this level of difficulty to each issue, we were thinking about contributor as a person that is first time contributor to open source in general and also if, if it comes to tasks like coding tasks, we're also thinking like yeah. Let's assume that a person that will jump into the issue is rather, maybe a junior or a bit more experienced developer.

A

So when you can see here, for example, that something is trivial, then it is really really trivial. It's like small, tiny change um in some document and when you see a level that is demanding well it's demanding, because you need to learn the project a bit to clone it to run tests um to start the project itself, so it's demanding in the way that you're gonna spend a few hours on it and not just like five ten minutes, but from the coding perspective, it's not as demanding as you could think.

A

It's not that you have to go through some discussion to implement.

A

So that's it. If it comes to the level of difficulty, then you have an information about the repository where it's happening. So as you can see, we picked issues across all the repositories of async api initiative and you can also learn about the source where we got the information from. So if you watched previous videos, you know that we are using sonar cube to monitor the quality of the project, so there are many issues that come from the solar cube.

A

Now in in this video, I will not go through the easy and trivial tasks, because yeah my assumption is that they are super easy, but um just keep in mind that if you don't find them easy, don't feel bad about it. I mean when we were assigning those levels.

A

We were thinking at the end from our position, people that are experienced um and, of course we might be wrong. So if we assumed something is easy and it's not easy for you, please accept apologies and don't be really afraid to work on the issue. Let us know you want to work on the issue, ask questions join our office hours and just don't give up. Let me then start going through the issues that are above the easy level.

A

So the first one is the moderate one from the generator repo and it's about docker. I think it's the only issue that we have for hacktoberfest, that involves.

A

Docker, so this issue is about improving the docker file that we have for the generator.

A

So what's the problem with the docker file, so the generator is an npm application and here in the docker file, what we do is we are building the project from scratch and we're using the cli in the docker image directly from sources, while the best practice would be to use here the official version of the cli that we pushed to the npm.

A

So in the issue description, you can find a an example of a docker image where you can see this approach, that instead of building the project from the sources and using in the docker image the sources, um the owner of the dockerfile, defined that the in the docker. When you build the image you simply install globally in the docker image, the application, the cli from npm- and that would be the best approach here, because docker is additional way of using the cli.

A

While it should use the released version. Even though the docker file and the release happens in the same at the same stage in the ci, we should still go forward with using the npm version.

A

So it's as simple as that, just changing the configuration of the docker file.

A

A

Demanding html template.

A

This issue is about us, rendering in the html documentation generated from async api document, additional special parameters that we're adding to the async api file when we parse it with javascript parser those x dash, parser properties, they're super useful for code generation for um for other things, but not when you render documentation for the user. You don't want things like x-parser parameter, showing up in the docs, as in the example of the payload.

A

That should not happen and we should hide these parameters from the ui. So it's a demanding issue because you need to first of all um understand, try out the parser, try out the the schema and in the html template how it's rendering. Why, in some cases, there's this x parameter showing up.

A

You have to later on understand how the generator that is using html template works. um How the templating works that in um generator we're using nunjucks templating, and you first of all have to understand how the templating works.

A

um It's not as handlebars it's similar, but it's different, and then you have to come up with an idea of a solution how to fix it.

A

So we're not telling you exactly how to do it if you should solve it with some statements in the template or maybe add some filters that we have in the in nunjucks in generator. So filters are, like usual javascript functions that you can use to.

A

Process the the data in the html template.

A

So it's a true demanding issue, but it's a really good onboarding issue for the asking api initiative and you know you can ask us for.

A

Help the next issue is from three different repositories. So basically, if you jump into this issue, which is demanding um you're going to end up at the end, with three pull requests to three different repositories, so it's like almost done with the oktoberfest and it's coding. So let's see what's it about.

A

Okay, so it's about highlighting um the the code blocks.

A

um So it's a request from davey there's an idea he had, which is pretty cool, that um with async api, like with open api in the document you can use markdown.

A

So, for example, let's say you have a description field for some for a document or some part of the document, and you can put there a long description with markdown and the idea is that there are people that would like to use this description to also put some code samples inside and then, if they would do it, they would expect that our markdown and html template they support it.

A

So they they have a functionality that can take that can take the um the code sample and change it into a nice sample in html, for example, with highlighted code snippet.

A

And why it's so complex?

A

It's because the functionality that is behind the rendering of markdown into html is that the function, the filter that we're using it at the moment in the html template it's in a separate repository, it's in the library with other filters. So, first of all, you just need to make this modify this filter in external repo and looking on the instruction modify code a bit, so it supports syntax highlighting and then once you have the pull request open.

A

You can go forward with opening a request in the templates to bump the version of the generator filters, and that's about it.

A

The next one about html template again html templating, demanding again because yeah you have to learn a bit of known jacks to be able to modify templates and it's about parameter description that is not rendered in the resulting html.

A

So, basically, when you have a in asking api, you have parameters for the channels and you can put descriptions for those, and the problem is that current html template does not render those descriptions.

A

So basically, at the end, you have a summary. What has to be done and some suggestion that maybe a specific nunjacks macro has to be extended and that's it next, one html template again: it's a moderate issue.

A

It's a not so nice bug. So the problem is with scholar types um in the rendered.

A

In the rendered documentation, so, as you can see here in the gif prepared by front expandable, chevron should be visible only whenever you have, for example, an object to show. So we need to expand and show more properties in the object, for example, but the problem is that at some point of time we got a bug in html template where we add the chevron actually to every property. Even if it's a string or integer and as you can see in this gif, um it doesn't really make sense to have this expandable item.

A

uh It's only confusing and looks not really nice. So it's a bit of javascript coding because there is a probably an issue with the filter that is responsible for deciding something is expandable or not.

A

So you need to clone the rep hole yeah and then investigate why this expandable filter is also marking these color types as expandable.

A

Next issue: html template again.

A

That's an issue that comes from solar cloud.

A

So solar clouds figured out that we have some duplication in the templates and the solution is to basically get rid of this application.

A

So you have instructions where this duplication happened, which lines are are duplicated and it's you can say it's easy. It should not be moderate but again it's um to take them outside from the template and make them reusable snippets in the template. You need to know what nunjax is. You need to know macros in nunjacks, and you basically have to create a new macro that can be reused across different template files.

A

So it's demanding because you need to read a bit: it's going to take a few hours and that's it.

A

The next issue.

A

Html template cicd config.

A

It's marked as moderate because you need to know have this basic knowledge about the github actions, because in this issue, what we, um what we have to figure out, what you have to figure out is that in html template we have a workflow that is triggered on a release and we're sending automatic tweet to twitter, saying that we have a new release.

A

The thing is: how it works now is that it's sending a tweet on any release like minor, major and patch, but we agreed with our community that tweeting about patches on twitter is not the best option. We had a voting and we decided that only major and minor releases are.

A

Important, so what has to be covered in this issue is to figure out how to in github actions, make sure that my action for twittering for tweeting is triggered only whenever there is a release, minor release or major release.

A

Never on touch and there's also a suggestion that it, it would probably makes more make more sense to change a bit. The existing workflow, because now tweeting is part of the of the workflow like release workflow, but um I think it would be much cleaner and much better to move it to a separate workflow. That would not run on a pull request merge, but rather on a release, create.

A

A

The next issue, javascript again.

A

Oh, that's a really nice issue, so um I was. I was doing some research recently on how we can um in easy way use current templates and give an option to the user that uh okay, your you're generating html. But if you want, you can also generate additional pdf with it and looks like the easiest solution is, and I tried it already on. My template is to use puppeteer.

A

So puppeteer is a a library from google that is using chrome, but it's also able to do it headlessly without launching a browser, and you can go through the browser and scrap stuff from it from the from the website, and it has an api that you can use to like open in a headless mode, a a website and generate pdf out of it, and I provided the links to the examples how it can be done. So it's not very, very difficult.

A

You just need to, of course, do some coding uh understand the linked code and extract the the parts that can be used in the html template, and it's also marked as moderate, because this functionality has to be added as a parameter option. So we need to read about generator as well what those parameters are where to define them and that's about it.

A

The next moderate issue is javascript. I think it's the last one from html template.

A

So it's pretty fresh, so we have a functionality in html template that you can generate just a single file with documentation. It's just one index.html file and the css and js it's all inlined in html, but there's a problem with it there's a problem with it that was figured out by by this user.

A

The problem is that inside the filter that is described here.

A

We are using an experimental function from node.js, which we should not use at all at the beginning, and experimental functions means basically that they are not subversion, that much they're not they can change every minor version and that's what happened here so we're using experimental version that with node.js 18 1218, it works fine, but with the older version, 12 8. As far as I remember, it was two: it works differently and it's causing errors and in docs we're saying that generator is compatible with node 12.

A

we're not specifying a a minor version, and we should make sure that uh it's really the truth. So what's um to be done with this with this issue, you simply have to go to the filter uh check out the part where we are using this experimental function, which is.

A

Fsmdr, it's a experimental function that removes recursively the directory and you basically have to replace it with some existing npm dependency. Just make a short research on some um npm modules that are capable of removing directories. Recursively.

A

Add it to dependencies of this template and use it in this filter actually hook.

A

Sorry and that's it.

A

Next one node.js template demanding.

A

Yeah, it's a docs, related issue. It is demanding, because um I mean to create a good readme template and create it first for one template and keep in mind that it can be used by other templates as a role model you have to, I mean, spend some time reading the docs about generator and the template play with it.

A

It's gonna take you a few hours to to get it, and then you need to come up with a a good structure, readme, which is a a lot of work from my perspective- and I have background in technical writing, so I think it's demanding, but it's also super super challenging in a way that you're going to learn a lot working on such a template um working on such a readme for the template and of course you can uh set up a session with me or front uh where we can talk to you and explain uh everything you need to know about generator templates and this particular node.js template.

A

We can give you a lot of explanation about it, so don't be afraid that you're going to stay alone with the issue, rather remember that we'll treat it like a issue that is solved by one of the members of our team. So in the past, from my technical writing experience, it's usually working like this, that you, as a technical writer, need to meet a special matter. Expert in the field, have an interview with him or her listen about the product about the functionality.

A

What are the options and then, as a typical work of technical writer, you have a lot of data in your head and you just need to spend some time to organize them in a nice, readme and yeah. That's about it! The next issue. It's.

A

Hard and yeah- I think it's hard.

A

I don't think many people will pick it up, but still it's um it's, I think, cool to explain. So this issue is about integrating a library with node.js template. It's a library that is created by one of our community members valid and it's about his asking api validator.

A

So what has to be done here so the async api, the spec that I explained in other videos in this spec you can describe an application. What it's doing if it's subscribing or publishing to some specific broker message broker.

A

So, which means that you can not only send messages to this broker, but you can also receive them and those messages, then can they can have different formats, and you would like to say, owner of the application, make sure that you're getting only the message that has a format defined, nothing api file and all the other messages will be refused and dumped into logs and that's what this validator is for and it's just about integrating it in a proper place in this node.js template and it's marked as hard because it requires more investigation.

A

Even from my side. I never use this validator, so I would have to definitely spend even on my own few hours to understand this, um this package from walid and how I can put it into this node.js template and then, of course, run the template and play with it and see if everything works. Fine.

A

And yeah: that's it.

A

The next one demanding parser.

A

Gs so we need to add a validation of the server variable variable example. So, let's yeah, let's look into the spec.

A

So according to the specification, wait a minute according to the specification, whenever you're describing a server in the document, you can.

A

Provide variables in the url and those variables can be later on described very well in a variables object and those variables object allows you to put not only the description, but also in examples.

A

Examples of such a variable and what needs to be done in this task is to manually, like manually in the code of course, verify that the example from the.

A

That example, from the examples is really matching the description in the anom field.

A

So if the inum field is, for example, I don't know like one two three and in the example you have four, then it's a failure right, it should not be. Such a document should be marked like as having an error, because the example is not matching the description of the variable.

A

And that's what has to be done here. The next moderate issue from parser.

A

It's about extracting the some code from one test to a external file, so we can reuse a function across tests and it's about the try catch issue in tests and that we have still in few other tests, it's fixed in main test suit for the parser.

A

So you basically need to take the function. That is there in the parse test. Js file, move it to a separate file in tests directory and then use this function, not only in the parse test js, but also in the async api, schema format, parser and custom validators.

A

So it's really used across all the tests.

A

Now the next one is demanding from the parser.

A

So it's a validation of operation id in operation trades. It's not moderate! It's rather demanding, because I know what part of the code it's touching, it's something that I wrote so the validation of operation id across the whole document- and I made a a tiny mistake I was in in the code in validation code. I was only checking the operation id across the operations and I totally missed the operation trades and it has to be, it has to be fixed.

A

So it's a bit uh more than just moderate, because I think it's it's gonna require the refactoring of the existing function for validation of operation ids, because it's already long enough uh that I think it's gonna trigger alerts in sonar cube uh that um the the length of the function affects the readability of the function.

A

But that's just my assumption um and you have a example yam file um against which you can test your functionality. So this part at least is it's easy. You have a good sample to test against.

A

The next one parser again so it's about adding the validation of query params in channel name.

A

So basically channel name is like the like url, you have word slash word slash word slash, and you should just make sure that nobody is using a url query parameters in the channel name and you should always validate such a document as invalid.

A

If something like this shows up in the channel name,.

A

The next one moderate again.

A

Yeah in this one, what you need to learn about the the async api and the parser, so async api allows you to define the schema of the message using different schema formats. So it's not only json schema, it can be even open api standard or it can be avro schema or ram data types. So many different ones and the the parser gives you a way that by default it's gonna always parse. The json schema as a default one.

A

But if you are using different schema formats, you can provide plugins for the parser that they should parse only a given schema format. Those plugins are super easy to write it's more complicated to parse a a avro schema into json, but then to make it pluggable for the parser. It's super easy and in this issue what's happening, is that um we're not really throwing a nice error message in the parser in case there is no parser for a given um schema format.

A

So if you, for example, define in your document that you're using avro schema, but you your sparser without the other plugin, the error, you're gonna get is not really nice right and instead of such a like meaningless error message, you should get a really nice parser error. That is going to tell you that there's no parser for the schema, registered, etc, etc.

A

um Come up with a good error message and in this issue you're going to have to register a new error type, which I suggest here like schema, parser not registered, but maybe you have a better idea, but yeah! That's that's about it.

A

The next one last two, both from password oh yeah, in the parser parser- is written with uh with javascript, but there was a request and we provided typescript types and we're generating them from jsdoc.

A

So it basically means we need to pay more attention to the quality of js dock and that we would usually do, and the suggestion in this uh issue is to try to integrate, with the current es, lint configuration a login for js doc validation.

A

So that's fairly easy, but yeah. The assumption is that there will be some errors, so you have to not only integrate the plugin but also fix potential errors with jstoc.

A

And the last one.

A

Extend the component model with has like functions so within the parser parser gives you a a option to extract data from the document in javascript, so you can, for example, pick up the message from a given channel if you want, um but there are elements, many elements in the in the async api document that are not mandatory, they can be provided even empty and what you would have to do is always like whenever you're writing some code generation or docs generation, you would also have to always have to like manually check if really um some data exists or not and there's this idea of having um has functions like has messages uh to make it much easier to check okay.

A

If does it have messages than do this? Does it have schemas? Does it have parameters?

A

At the moment we have a lot of hash functions, but not for all cases- and here you can see a list of cases that I discovered where we're missing those as functions.

A

So it's about adding really simple hash functions to the components model, so everything will go to this file and yeah. There's no hass function there, but I think I linked yeah. I linked an example has parameter.

A

Function from the channel model- and you now can ask a question like what I mean like if you have it already, but just keep in mind that async api is designed in the way that you can put everything in one place in one location. But if you want to reuse and not duplicate yourself, then there's a components: object where you can put reusable parts of the of the document and then then refer to them from the main part of the document from the channels.

A

So in the channels you can see that you can easily check if a given channel has parameters, but it's not so easy. If you have a channel that just has a reference to the components object where parameters are so you basically would like to have an option that you go through the component object and before iterating over parameters you'd like to know if parameters are even defined, so you do like s parameters and then you can react if you get a true or false, of course, in response, so that's this.

A

What's this issue is about, so I went through all the issues, not of course, the the easy and trivial ones. As I said at the beginning, like I can imagine that many of those issues are can still be hard uh to start with, especially if you don't have this knowledge about generator and our dogs, maybe stuck in this area or you don't have enough knowledge about the asking api document.

A

You don't even have enough knowledge about even driven architectures, and you have a feeling that they are important here and you need some additional explanation, but you can't find anything clear in the internet.

A

Remember again, I'm going to remind you that we approach the octoberfest in the way that we really want to be as open as possible to you. So just remember, we have those office hours that you can join and talk to us where we can explain things for you, but if you don't want to like enter a discussion with video um where others can listen to, it feel free also to join our slack and ask us for support there in a more asynchronous discussion.

A

If you want just keep in mind that both me and fran were super open and uh would love to help anyone in this uh yeah hard first step into open source, but once you do it you're, not regretted good luck and happy coding.