pitkley / aws-search-extension Goto Github PK

Preface
By using renovate, dependabot and bors this project already does a lot to easen the burden of testing and keeping the dependencies up to date. Still forming new releases may be a big hurdle, with all the tasks to pull off and the ceremony of the whole affair.
This hurdle is higher the more time lies and the more changes happen between releases: testing is getting more complicated and effort.

As a developer
you want to only care about the code and features and not be bothered with doing/initiating releases or even the decision on when to release.

As a user
I want to have new features and updated indices on a regular basis.

Feature request
Using automatic releases on each merge to "main" would take away these issues.
"semantic-release" for example allows to define which kind of release (patch, minor, major) it will do for the type of commit it will find in the commit log. So you can decide beforehand if submodule updates by renovate will trigger a patch release (or none at all) for example.
One thing to note though is: commit messages need to follow a certain schema for semantic-release being able to parse them properly to follow these rules.

Side note
Another possible solution have updated indices out for the user regularly is discussed in issue #16 - but this issue is mostly about automatic releases for code changes.

Following the announcement of "Retiring the AWS Documentation on GitHub", the aws-cloudformation-user-guide was finally removed of its content last week (2023-12-08). The aws-sam-developer-guide hasn't had content since June 2023.

We now need an alternative way of creating an index for the CFN docs. The AWS CloudFormation resource specification is a potential candidate for programmatically identifying resources that exist. The main challenge is going to be generating valid URLs out of it -- from what I recall, the naming scheme of the URLs for the individual pages in the CFN docs was not consistent. It also does not solve the problem of getting a summary into ASE, but we could worst-case just skip out on that.

I don't yet know if something similar for SAM exists.

• AWS CloudFormation resources
  #201
• AWS CloudFormation intrinsic functions
  #201
• AWS SAM resources
  #209

It would be super helpful to also include AWS CDK documentation in the search results.

First of all: many thanks for this great and helpful utility!

As a user I would like to have an up to date search index.

various solutions came to mind:

• update index on extension loading (righ after browser start)
• update with click on a button/menu item
• timer-based polling if new index is available

Clean up the code for generating the CloudFormation search index and integrate it into the repository, i.e. the search-index should be generated as part of CI, rather than be committed.

Maybe we can also think about how we update the index for deployed extensions, i.e. should we have a mechanism that automatically downloads it? I think the rust-search-extension does something along those lines, although I haven't exactly found out, how.

I recently broke (4ad973a, fixed in 29f84e7) index creation for the CloudFormation index. I think it would be sensible to add a CI step that ensures the a generated index follows the form expected by the extension.

I'm thinking about either a very simple process that verifies the basic structure and field-counts, or going a tiny bit further and using a JSON-schema to verify the results.

The Chrome extension we definitely cannot sign before publishing, but the Firefox extension can be signed and uploaded elsewhere, IIUC. We should do that! 🙂

Wonderful job with this extension!

While experimenting with it, I found a problem. When I type ase :Bucket it opens https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3-bucket.html which redirects to https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html

The proper URL for AWS::S3::Bucket docs is https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket.html

Screenshots:

In case anyone has a version <=0.3 of the extension, they'll be mightily confused when suddenly the aws keyword will change to ase. A popup should be added notifying the user of this important change.

The popup should not necessarily be a general thing, most likely just for breaking changes or major new features; for right now it should be created specifically for the keyword change.

How to implement:

• Create an HTML-page describing the changes (extension/popup/updates/<something>.html might be a good location).
• Add a background-script that executes browser.runtime.onInstalled.addListener(...) (main.js can probably be reused for this).
• Verify what version we are upgrading from and to in the listener, exiting early if there is nothing to report.
• Use browser.tabs.create(...) to open the HTML matching the upgrade in a new tab.

I'm not yet sure how this should work. If we want a single search-endpoint for all API references, or if we want to give the user the opportunity to search a specific service (or both?).

I think a per-service search definitely makes sense, although since that will require that the user knows, what the service-name we use internally is, we'll probably have to support the one-search option too.

My current idea for the UX, since I'm heavily biased towards the CFN completion, would be this:

• no prefix: CFN results
• /: all API results
• <service>/, e.g. s3/: per-serivce API results (this can probably be achieved through the regex-matcher)

AWS SAM provides its own (pre-transform) resources, for which it would be great if they were searchable by ASE as well: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification-resources-and-properties.html.