avinal edited a comment on issue #6461:
URL: https://github.com/apache/apisix/issues/6461#issuecomment-1061477443
Hello all, Thank you all for the review. here is the update for the proposal
based on your suggestions.
> Could the description of 'external plugins' more deliberated? I think
there could have several documents to introduce the way to write plugins in
different languages.
Yeah sure, there is just one problem, since external plugins may or may not
be supported by APISIX, we can only explain the preferred way to write them and
not explain every possible way. It would be good to have different pages for
different writing methods.
> It depends what you mean by "little introduction". I really dislike coming
to a project I don't know, and being presented with the update of the latest
versions, but not understanding what it is about.
Little introduction means just necessary stuff about the project, neither
too deep nor too shallow. I will add some explanation.
Thank you for the examples, will add something similar to this doc as well.
> 1. Getting Started → Contribution Guide/Community Guide: How about linking
to
[`https://apisix.apache.org/docs/general/contributor-guide`](https://apisix.apache.org/docs/general/contributor-guide)?
Both ways are possible, either we can move the whole doc to the contributor
guide section or just link it. Since the doc is already there, it would be nice
to just link.
> 2. Usecases/How-to Guides: Are they the same contents?
There is a slight difference between these two topics. The use cases are
what we intend the application to be used for. And how-to Guides are questions
answered from a particular use-case perspective. In general, they mean the
same. I put it there just to decide which topic to use.
> 3. API → AdminAPI: Will we split different entities into different
sections?
If there are separable entities then it makes sense to split them into
different sections. Right now the page is just too large, ideally, one page
shouldn't contain more than 2000 words(excluding code), or it becomes too hard
to follow and search. So splitting will be nice.
> 4. Plugins → External Plugins: Just to make sure, do you mean Java/Go/xx
Plugin Runner or plugins made by unofficial members? e.g
[`https://github.com/swisscom/apisix-opa-plugin`](https://github.com/swisscom/apisix-opa-plugin)
Yes, we can list popular external plugins and the preferred method to create
them. This will expand the applications of APISIX.
> 5. Plugins: Many developers report that they cannot work well with Plugin
Development in different machines/environments, could we have some recommended
environments? or PDK (Plugin Development Kit, @tzssangglass is familiar with
this).
Yes, that is why we are going to a plugin development section. And we can
then suggest the best practices for plugin development.
> We can add security, observability, Kubernetes deployment, multiple
development language development plugins, WASM, etc. In the protocol part, MQTT
and GraphQL are also worth mentioning.
Sure, I am not very familiar with the protocols, will add them once I have
discussed them with the engineers.
> Would it be better to add a `Concepts` section to introduce `route`
`service` `consumer` `upstream` ?
Yeah, I have already added that `Definition of important keywords` inside
`architectural design`, but `Concepts` seems a better choice of word, please
suggest if I should move them out in a separate chapter instead.
> Perhaps a `Plugin Development` directory is needed to collect
documentation related to plugin development.
>
> under `Plugin Development` maybe:
>
> 1. Build development environment
>
> 2. Development Process
>
> 3. Development and debugging skills
>
> 4. Writing test cases
I have added this as `Creating custom plugins`, but `Plugin Development`
seems more suitable, will rename it and add the suggested sections.
> Besides these aspects, I hope that the below things can be added:
>
> 1. Guide about openresty/ngx_lua development (give some materials are
also good);
>
> 2. Not only how to write case but also how to run them;
>
> 3. The Plugin Development Kit docs
Seems like a great addition to me. Will add them as well.
> Hi, I have a little advice here:
>
> * I think it would be a good idea to put the learning APISIX and user
cases into a single place like a learning library.
That would be more clear and expressive, Will restructure.
> Maybe add `Best Practices` ? e.g. Different cluster size and best
practices , Upgrade best practices , ide best practices(idea emmylua plugin,
vscode+emmylua plugin , zbstudio ...).
>
> e.g. ansible best practices
https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html
There was some consideration at first but haven't thought about it much. I
will see them and add them. Thanks for the example.
**I have added all the suggestions to this comment. Please feel free to add
more suggestions**
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
