🗳️ Archiving Inactive Repositories

[quetzalliwrites]

We've identified several AsyncAPI GitHub repositories that have been inactive for a significant period:

• asyncapi/asyncapi-react
• asyncapi/html-template
• asyncapi/markdown-template
• asyncapi/nodejs-template
• asyncapi/openapi-schema-parser
• asyncapi/extensions-catalog
• asyncapi/raml-dt-schema-parser
• asyncapi/nodejs-ws-template
• asyncapi/generator-hooks
• asyncapi/generator-filters
• asyncapi/enterprise-patterns

We believe these repositories may no longer be in active use (zero or one active maintainer), and archiving them will help maintain a cleaner and more organized GitHub environment.

Let's use this discussion thread to:

1. Share any insights or objections regarding the archiving of these repositories.
2. Identify any critical reasons to keep a particular repository active.
3. Discuss the archival process, data preservation, and implications for contributors and users.

---

cc @fmvilas @derberg @AceTheCreator @Barbanio @smoya

[fmvilas]

Honestly, I think every repo listed there can't just be archived. Maybe the enterprise-patterns one can be archived. The rest are heavily used by other tools like Generator and Studio or are important to the future of the spec like the extensions-catalog one. I would try to find maintainers instead of archiving them.

[Shurtu-gal]

Yeah, all templates are being used in some way or other by generator and cli.

[smoya]

I'm gonna try to summarize the meaning and potential usage of each of those repositories, with the intention of adding more context:

• asyncapi/asyncapi-react
  • It is the core library for generating documentation based on an AsyncAPI document. Used by the [asyncapi/html-template] (https://github.com/asyncapi/html-template). Can't be deleted/archived
• asyncapi/html-template
  • Used for generating the documentation in HTML files from an AsyncAPI document. Can't be deleted/archived
• asyncapi/markdown-template.
  • Same as the previous one, but the output is .md instead of HTML files. Useful for READMEs, etc. I believe this is very useful for generating documentation hosted in Github or any tool that renders Markdown, so I would say we should not delete it.
• asyncapi/nodejs-template
  • I believe it's, after the ones that generate documentation, the most used generator. However, it is so simplistic and useful mainly for generating code that can be used as an example or basic bootstrapping.
• asyncapi/openapi-schema-parser
  • Used in parser-js for parsing Schema objects with openapi format, which is one of the several formats the Schema supports. Can't be deleted/archived.
• asyncapi/extensions-catalog
  • It aims to host the list of "official" AsyncAPI extensions. Not pretty useful at this moment IMHO because is not being used by the Parsers but there was an ongoing work to do so: Integrate the extension catalog with the JS parser parser-js#803, which then will totally reach an important status, so +1 to find maintainers here.
• asyncapi/raml-dt-schema-parser
  • Same as the openapi-schema-parser. Can't be deleted/archived
• asyncapi/nodejs-ws-template
  • Similar to the nodejs-template, but creates code for websocket protocol. Could this be merged into the nodejs-template? 🤔
• asyncapi/generator-hooks
  • Those are hooks (actually there is only one...) that can be set in your generator templates to tell the generator "Hey, after generating code with me, please also do this other thing". In the current case, there is only one hook that allows to include the source AsyncAPI document file into the generated directory. I completely think this extensibility is nice, but obviously could be integrated in the Generator directly as an option somehow. Anyway, this is being used by some templates, such as the node-ws-template here.
• asyncapi/generator-filters
  • Contains reusable filters for the templates. But as far as I see, those are for old template system (nunjucks), so I believe this can be archived.
• asyncapi/enterprise-patterns
  • It aims to translate some EDA common enterprise patterns to AsyncAPI document(s). I like the idea, but it requires a lot of work anyway. I believe this could be archived but could be taken as a source for a new series in our docs, more enterprise-solutions-oriented?

cc some stakeholders here @magicmatatjahu @fmvilas @alequetzalli @derberg

[Tenischev]

asyncapi/generator-filters
Contains reusable filters for the templates. But as far as I see, those are for old template system (nunjucks), so I believe this can be archived.

No it can't

I believe this thread need attention of all @asyncapi/tsc_members

[quetzalliwrites]

Thank you for the summary @smoya 🦖

[smoya]

@Tenischev archived is not the same as deleted. We won't archive any repo without the explicit consent of the TSC. Look at this example https://github.com/orgs/asyncapi/discussions/1045.
This discussion is that, just a discussion.

Btw, would you mind sharing the reason why that repo can't be archived? This is what this discussion is about, to find usages, etc.

[thulieblack]

The asyncapi/nodejs-ws-template can't be archived as it is currently being rewritten to the new parser and react.

I suggest keeping the generator templates for now, as I know a few folks who recently used them for instance, the asyncapi/html-template and asyncapi/html-template

[thulieblack]

hehe actually, it's the nodejs-ws-template that is being refactored from the old Nunjucks templating engine to React.

[derberg]

Why are we rewriting this template to React? 🤔 Any idea? It's weird because this template uses an unmaintained library of mine that eventually evolved to what is Glee today 😅 So I would not have this template and instead tell people to use Glee. It's essentially the same but better and maintained 😄

It is in rewrite process as it is maintained and the goal for templates should be to migrate all of them to react and enable us to drop Nunjucks support in the generator.

It's weird because this template uses an unmaintained library

parser-js also relies on $ref parser that is deprecated and archived 🤷🏼 not to mention ajv that is also lacking proper maintainance. The fact that some dependency do not evolve or at some point of time lacks some maintainance should not be a reason for archive.

[fmvilas]

It is in rewrite process as it is maintained and the goal for templates should be to migrate all of them to react and enable us to drop Nunjucks support in the generator.

I'd suggest to completely drop the template instead of migrating it. It doesn't make sense to keep providing the template when we already have another mechanism to generate a Node.js project that does the same plus much more 🤷

parser-js also relies on $ref parser that is deprecated and archived 🤷🏼 not to mention ajv that is also lacking proper maintainance. The fact that some dependency do not evolve or at some point of time lacks some maintainance should not be a reason for archive.

Well these libraries you mentioned were "production-ready" and heavily used by other people at some point. My library was never tested in production and there were known issues that were solved in Glee but not in my library. So yeah, tomatoes and oranges.

[derberg]

archive/deprecated is not cool no matter how adopted the tool is as it puts the dependent project in dead end when some changes have to be done. Then only solution is fork-fix or move to another library. No matter if Heres or ajv 🤷🏼

whatever you mean by tomatoes and oranges - basically the fact that library uses a dependency that is not maintained is not at all a reason to archive the library 🤷🏼

also Glee is also not tested in production 🤷🏼 and also I'm not aware of what problems you had there on Hermes that were solved with Glee.

when we already have another mechanism to generate a Node.js project that does the same plus much more

what mechanism are you referring to?

---

anyway, if you want to continue discussion about removing template - please open an issue in the template itself to make discussion visible to potential users as here it is basically hidden.

[fmvilas]

whatever you mean by tomatoes and oranges

Just to clarify, this means that we're comparing two very different things.

I'm not aware of what problems you had there on Hermes that were solved with Glee

Hermes was a proof of concept. Nothing else. It was never finished as in it was missing basic functionality like passing a user/password to connect to a broker or use any authentication mechanism. Therefore, not suitable for production.

what mechanism are you referring to?

CLI + Glee :) CLI + Glee is a mechanism for you to generate a Node.js project from your AsyncAPI file. And this is where we're investing most of the effort, right? I mean, from the two options, not at AsyncAPI in general.

anyway, if you want to continue discussion about removing template - please open an issue in the template itself to make discussion visible to potential users as here it is basically hidden.

I have no specific interest in removing that template. I was just replying with my thoughts here. It all started here: https://github.com/orgs/asyncapi/discussions/1043#discussioncomment-8320950. I just shared that instead of migrating it, I'd (I would) drop it. But that's just an opinion.

[derberg]

Can you please clarify basing on what factors did you select these specific projects?

For example, to identify the least active repos, you can go to https://github.com/orgs/asyncapi/repositories (by default sorts by activity) and see the last ones on the list:

• https://github.com/asyncapi/shape-up-process
• https://github.com/asyncapi/enterprise-patterns
• https://github.com/asyncapi/parser-go
• https://github.com/asyncapi/converter-go
• https://github.com/asyncapi/python-paho-template

only one of those is in your list. Still, there should not be a single "bucket" discussion about a bunch of unrelated projects. Instead, there should be first an individual discussion with maintainers of given repo, best if first offline because there might be many different reasons maintainers are less active (in many cases it is for personal reasons) and public call out without a clear reason why this happens puts people out in uncomfortable way. For example I feel uncomfortable that I have to now, without any clear reason explain why we should not archive generator-filters. Discussion must start first in related repository, like here for example asyncapi-archived-repos/cupid#182 (and I first had offline discussion with Arjun to make sure he is aware we need to do something to move on with the project).

TSC should not archive any repository if at least one of its maintainers do not agree to do it. AsyncAPI Initiative should help finding maintainers or maintainers funding.

Can you please clarify why this discussion is started as a "bucket discussion" for several unrelated projects?

Like why? 😄 are you on some kind of cleanup mission? We believe these repositories - who is we? If you want to do audits like this, as discussion about archive on day one, can you first please make a proposal and document basing on what factors a repo is part of the audit? like what it means "it is inactive" or "how you determine there are no active maintainers" - do you base it only on github data? what does it mean "maintainer activity"? do you measure responses in issues? or just PRs review - and why?

---

so yeah, for me archive is last resort - not much different than deletion (deletion should anyway never happen in open source) and I'm surprised we start discussion about archiving without any initial explanation and background story.

[fmvilas]

Can you please clarify basing on what factors did you select these specific projects?

I think I can take this one. This is coming from a conversation between @smoya @alequetzalli @Barbanio @AceTheCreator and I. I was sharing this list which is a subset of the repos I monitor that need attention. I was trying to convey that the Community Growth WG(1) could be taking care of working with the maintainers of these repos to find and onboard new maintainers. And, of course, propose to archive those that don't make sense (if any) or we can't find anyone interested in maintaining.

This seems like a misunderstanding. Even if we worked to archive them, it should never:

1. Be decided by us but maintainers and then TSC.
2. Be discussed in a bucket discussion because every repo has its own "things" and it should never be discussed outside the repo realm.

So yeah, just to clarify, this is a misunderstanding and I apologize for the unclear messaging that I have used and that could have provoked all of this.

(1) For those reading, by "Community Growth WG" I mean the AsyncAPI "subteam" at Postman.