feat: docs feedback form created

[akshatnema]

Description
This PR is related to issue #453 where I have added a Docs Feedback Form at the end of each doc to take feedback from the users and store it in a Google spreadsheet connected through Google OAuth and Google Sheets API. So far discussed in the issue, I have implemented the design in the PR and it is working fine. Also, the backend facility of taking the data to the spreadsheet has been made and it is in my local dev environment. It is because some Google environment variables are not set in the netlify deployment, so the facility will fail on the deployment as soon as it is pushed. I request the maintainers and community founders to kindly add more environment variables in the production to make this feature fully responsive on the website.

Here's the list of env variables to be added:

• CLIENT_EMAIL - Google Service Account that will be added as an Editor role in the spreadsheet to add the data
• CLIENT_ID - Provided by the Google Developer console for the access of APIs.
• PRIVATE_KEY - Provided by Google for OAuth purpose
• SPREADSHEET_ID - Provided by Google Sheets on which spreadsheet we will be storing the data.

Apart from the above variables, we need to create Google Service Account (if hasn't been created yet) and enable the Editor role to that account in the spreadsheet. I will highly recommend if @magicmatatjahu or @fmvilas could connect to me in a call for further explanations of what exactly will be needed to set up the variables. This PR will be as a draft PR till the environment variables and the backend will be pushed in the repository. Any suggestions are warmly welcomed on this PR 😄.

Preview of the backend facility from my local dev environment

2022-02-28.12-33-43.mp4

Related issue(s)
Resolves #453

[netlify]

✅ Deploy Preview for asyncapi-website ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	f4d8a2a
🔍 Latest deploy log	https://app.netlify.com/sites/asyncapi-website/deploys/626578b6c36a7f0009c5715e
😎 Deploy Preview	https://deploy-preview-609--asyncapi-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[akshatnema]

As discussed in the issue, we can have netlify functions to implement the functionality for implementing the process. Right now, data is going through a POST request and it is handled inside a api folder in pages. If you think that it should be separately done in netlify, then I will look in something more on how to implement it in that way.

[magicmatatjahu]

@akshatnema Thanks for that PR. I don't have permissions to create/setup such a envs and then connect them in the Netlify (we need your help @fmvilas @derberg).

As I understand you have backend but you didn't push it. Of course you can, it's not a problem. We don't need to wait for envs. However I'm not a fan of having access to that envs in the PRs. Why? People can make simple console log and then log all envs that we have. It's not a good idea. As I know Netlify has possibility to setup envs only for master branch and currently we use that for Zenhub and Github tokens (for fetching the roadmap data).

About Netlify function or API on the NextJS side: we use the static site generation, but if that API works with static site (please build site and then host it in your local machine and try run that API) we can go with that solution, it will be perfect :)

So please push changes for API and I can make review.

[akshatnema]

@magicmatatjahu Yepp, I pushed the backend in the PR. And as expected, the form will not work as there will be an internal server error (shown in the Browser console window). This happens because there is no OAuth and spreadsheet connected to it using envs. API is working perfectly fine in my local environment as you can see in the preview above, but I can't able to deploy it on my Netlify account. Errors are already sent to you on Slack. I also want to raise certain issues on design perspective and want to discuss with you:

1. While submitting the form, right now we can't able to categorize feedback in the sheets. We do have to pass a name parameter in the sheets to perfectly identify on which doc, feedback has been sent by the user. It is not a big task and can be done very easily.

2. Right now, Feedback form is right at the end of the doc. But, what I prefer is to have this component before Up Next and Go Back Buttons. It is ideal place to render this component there. What we have to is to add the Feedback component at the end of each doc (on each md file), before the buttons. Will this be a good idea to do?

Preview of the Server error on the preview:

[magicmatatjahu]

@akshatnema

Yepp, I pushed the backend in the PR. And as expected, the form will not work as there will be an internal server error (shown in the Browser console window). This happens because there is no OAuth and spreadsheet connected to it using envs. API is working perfectly fine in my local environment as you can see in the preview above, but I can't able to deploy it on my Netlify account. Errors are already sent to you on Slack. I also want to raise certain issues on design perspective and want to discuss with you:

Please don't worry, as I wrote, we should not add access to these envs on the PRs, because people will be able to log them. They should be only available on master build.

Also I see that your PR was properly built, so is there a problem yet?

While submitting the form, right now we can't able to categorize feedback in the sheets. We do have to pass a name parameter in the sheets to perfectly identify on which doc, feedback has been sent by the user. It is not a big task and can be done very easily.

You should retrieve name of doc from NextJS Router Context (I guess, you should test it) :)

Right now, Feedback form is right at the end of the doc. But, what I prefer is to have this component before Up Next and Go Back Buttons. It is ideal place to render this component there. What we have to is to add the Feedback component at the end of each doc (on each md file), before the buttons. Will this be a good idea to do?

I checked some sites (including NextJS documentation) and I see that feedback form is always after the next/prev buttons so I think the current location is good :) In addition, we could display only the "add feedback" button at the beginning and when someone clicks it, the whole form will appear. Currently it is very "explicit" (I don't know how to describe it 😅 ) in the documentation and people can focus on it and not on the documentation.

[akshatnema]

You should retrieve name of doc from NextJS Router Context (I guess, you should test it) :)

@magicmatatjahu Ok 👍, will definitely look into this and will update the backend accordingly.

In addition, we could display only the "add feedback" button at the beginning and when someone clicks it, the whole form will appear

Ok, will look into this and I will try to implement it in a better way. As it was not mentioned before in the issue, I haven't thought of it yet.

[derberg]

@akshatnema token on Netlify that has rights to create discussions is there, env name -> GITHUB_TOKEN_CREATE_DISCUSSION

[akshatnema]

@derberg Thanks Lukasz for creating it 😊. It will be needed when this is pushed in production. But, I need some more details regarding createDiscussion functionality. Here are they:

• Will the functionality be creating a discussion on this website repository or some other repository (asyncapi/community 🤔) will be specified for creating Discussions?
• Please create a category in the Discussions of the repository because it will be needed in the mutation of the graphql query.
• As you can see through the design, we are only taking feedback and it will be taken as our body of the discussion, but how we will be providing a unique title to each Discussion created. Can you specify any criteria to name them?
• For each Discussion created, we have to distinguish from which doc page, the feedback has been submitted. For this, my approach is to push the title of doc OR slug of the doc to the title of the Discussion created. But, if 2 or more feedbacks are generated from the same doc, then we need to append some numbers at the end of each Discussion title to uniquely identify them.

I will also like a review of @magicmatatjahu on the above questions mentioned.

[derberg]

@akshatnema

• it will go to website repo
• Docs Feedback category created https://github.com/asyncapi/website/discussions/categories/docs-feedback. @alequetzalli we can rename if you want.
• IMHO we can copy approach that I know from giscus that I use for my personal blog to have comments functionality. So there is always one discussion per path. Then each new feedback is another comment. Example blog/topbad3oss2021 derberg/derberg.github.io#60. What are the advantages:
  • you can quickly see which documentation pages get most feedback
  • feedback = comment is ok as you can still have thread discussion under a comment.
  • single comment can be used to create a followup issue
  • @alequetzalli can for example use emojis to mark comments that are already actionable for example, and she can process feedback for one document in one view

But I have to say I do not really have a strong opinion on above 🤷🏼 except for that I think it must be website repo

[akshatnema]

But I have to say I do not really have a strong opinion on above 🤷🏼 except for that I think it must be website repo

@derberg the approach you mentioned is even more hard to implement because if you see the implementation and rendering of the component, you will find that on each doc, the same component is rendered without any specific components for each doc. This means that the feedback submitted on a doc, the response we get back can be seen from every doc 🙂. So, that's what I am planning to have either NextJS Context or some variable to uniquely identify the feedback for each doc. We can surely can't make comments approach (as mentioned by you) because there are no different routes defined for the POST request made in the component. Hence, I will suggest to have createDiscussion functionality for the feedback.

[quetzalliwrites]

• it will go to website repo
• Docs Feedback category created https://github.com/asyncapi/website/discussions/categories/docs-feedback. @alequetzalli we can rename if you want.

Feedback on discussion category URL

Hey, @derberg and @akshatnema! 😄 Just a comment on the created Docs Feedback discussion category suggested above.

I already have a Docs discussion category going here and I think it makes more sense to use that one:
https://github.com/asyncapi/community/discussions/categories/docs

Question on SUBMIT button in feedback card

I used the Netlify preview link to test how the feedback card is working so far. I see that the SUBMIT FEEDBACK button still doesn't do anything. This is expected, right? Just wanted to make sure.. I assume it's because we still are figuring out how that button will work 😄

[akshatnema]

I already have a Docs discussion category going here and I think it makes more sense to use that one:

Fine, I will add the category and repository ID to that one in mutation. It will then create the discussion on that particular category 🙂.

Just wanted to make sure.. I assume it's because we still are figuring out how that button will work 😄

@alequetzalli Regarding the working of this button, yes it is not working right now because I pushed the backend of the form, using Google Sheets API, but due to the unavailability of environment variables, it will not work right now. I recommend you to read the description of this message #609 (comment). See the preview of the button (as shown in the video) and you will get what it does.

[akshatnema]

Hey @magicmatatjahu @derberg @alequetzalli, I have made the backend functionality of creating a GitHub discussion on Docs category of community repository. Although, the preview shown in the video contains the Discussion of my own project (for my testing), but I have updated the IDs to make a Discussion on Docs category. I want a review from all of you regarding the changes made and your suggestions are welcomed 🙂.

Preview of the Functionality:

GitHub.Discussions.mp4

Keypoints to notice

• The title of the Discussion - I'm not quite sure whether the title of the discussion made, is correct or not. So, I want your suggestions on how to modify and make it meaningful.
• The creator of Discussion - Although in the preview, it is shown that the Discussion has been made using my ID, but it is not that one. It depends on the bearer token used for making the backend. So, it depends on Lukasz from which account he has made the Personal Access Token.

[quetzalliwrites]

@akshatnema WOW, thank you for all of your work!!!!! 🎉🎉❤️✨✨

There are just some English typos/grammar fixes, and then we're done from the TW side. ✌🏽

[derberg]

I think we got this 🚀

@alequetzalli and @magicmatatjahu also must approve as they requested changes

[quetzalliwrites]

LGTM 🚢🚢🚢🌈🌈✨✨✨✨✨

[akshatnema]

@derberg any updates for this PR?

[magicmatatjahu]

As everyone who was supposed to give approve gave approve, I merge. Let's hope there are no bugs in production 😄

[magicmatatjahu]

/rtm

[derberg]

Something ain't working 😅

[derberg]

in the console I get 401 error but I checked and token is there in Netlify, with the name as you have it in code 🤔

[magicmatatjahu]

@derberg Could you check logs of the Netlify Function? I don't have permission, but you should. We print error to the console, so there should be more info.

[akshatnema]

@derberg @magicmatatjahu So sorry, I found the error immediately. I forgot to change the category and repo ID after testing. I checked it right now and will soon correct it with the actual ones. Secondly, I got that in error view, Create Issue Button is not aligned correctly. I will make it correct and make a PR in a few minutes.

[derberg]

@akshatnema It is still failing after redeploy of the fix 😅

INFO   RequestError [HttpError]: Bad credentials
    at /var/task/node_modules/@octokit/request/dist-node/index.js:86:21
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async Runtime.exports.handler (/var/task/netlify/functions/github_discussions.js:16:32) {
  status: 401,
  response: {
    url: 'https://api.github.com/graphql',
    status: 401,
    headers: {
      'access-control-allow-origin': '*',
      'access-control-expose-headers': 'ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset',
      connection: 'close',
      'content-length': '83',
      'content-security-policy': "default-src 'none'",
      'content-type': 'application/json; charset=utf-8',
      date: 'Mon, 25 Apr 2022 11:49:42 GMT',
      'referrer-policy': 'origin-when-cross-origin, strict-origin-when-cross-origin',
      server: 'GitHub.com',
      'strict-transport-security': 'max-age=31536000; includeSubdomains; preload',
      vary: 'Accept-Encoding, Accept, X-Requested-With',
      'x-content-type-options': 'nosniff',
      'x-frame-options': 'deny',
      'x-github-media-type': 'github.v3; format=json',
      'x-github-request-id': 'E36C:2B43:297E7C7:505CBB2:62668AD6',
      'x-ratelimit-limit': '0',
      'x-ratelimit-remaining': '0',
      'x-ratelimit-reset': '1650890982',
      'x-ratelimit-resource': 'graphql',
      'x-ratelimit-used': '0',
      'x-xss-protection': '0'
    },
    data: {
      message: 'Bad credentials',
      documentation_url: 'https://docs.github.com/graphql'
    }
  },
  request: {
    method: 'POST',
    url: 'https://api.github.com/graphql',
    headers: {
      accept: 'application/vnd.github.v3+json',
      'user-agent': 'octokit-graphql.js/4.8.0 Node.js/14.19.1 (linux; x64)',
      authorization: 'token [REDACTED]',
      'content-type': 'application/json; charset=utf-8'
    },
    body: '{"query":"\\n        mutation { \\n            createDiscussion(input:{repositoryId:\\"MDEwOlJlcG9zaXRvcnkzNDc2MjE1NTk=\\", categoryId:\\"DIC_kwDOFLhIt84B_T4d\\", title:\\"Feedback on /docs/specifications/v2.3.1-2022-04-release.1 - Mon, 25 Apr 2022 11:49:40 GMT\\", body:\\"This release candidate was released by mistake and should be actually removed from the website with all related redirects. Only 2.4 RC is valid\\"}){\\n             discussion{\\n               url\\n             }\\n           }\\n        }","variables":{"owner":"asyncapi","repo":"community"}}'
  }
}

[derberg]

@akshatnema we only need a token of write:discussion scope, right?

[akshatnema]

@derberg Nope, it requires more than that. More specifically, it is kind of GitHub OAuth added to the backend which approves that the user is verified and then allows creating a Discussion. Hence, you need to give more permissions to the token. Following image will describe which permissions you need to give.

You can probably not give delete_repo and admin:repo_hook permissions but have to give the rest of the permissions to the token.

[derberg]

ok, not a token problem, I recreated it, with all possible scopes, like a god mode, and still Bad Credentials

[derberg]

GITHUB_TOKEN_CREATE_DISCUSSION is the name of env variable in Netlify, so correct one

[akshatnema]

The issue is only related to the authentication (since it is giving the error of 401). You can try to deploy the website again by using the feature Retry Deploy without Cache on netlify after updating token. From my token, I am able to create the discussions on the repo, I'm not sure what's wrong going on with token in production. You can again deploy the website if you want to make it a try.

If you couldn't, let's catch up someday in a Zoom meeting where we can surely check it out from the logs what's going wrong in production. I'm not free this week probably because I'm having my exams so you can arrange a meeting on 29th April around 6PM (IST) or in the next week. I'm even free on weekend if you are suitable with 😅.

[derberg]

I checked token with my postman client to call GraphQL API in the way you do it in your code and it worked fine. This is not needed but still, it should not cause 401

[akshatnema]

I checked token with my postman client to call GraphQL API in the way you do it in your code and it worked fine. This is not needed but still, it should not cause 401

It hasn't created any error in the local environment yet. I'm not sure if this can create 401 error at production.

[derberg]

oh, I was actually now aware redeployment is needed after variable value change....Martin Fowler would not be happy about it 😆

Lemme try

[akshatnema]

@derberg We did it 😄. But please delete this discussion so that Alejandra doesn't take it as feedback given on docs 😃.

[derberg]

yay asyncapi/community#340

congrats @akshatnema on amazing implementation 👏🏼

[akshatnema]

Thanks @derberg. I think you should now create an issue in the website repo on how to improve the title of the Discussion created by feedback. It is really looking very awkward right now for me.

[derberg]

yeah, let's see how people use it first, how often, etc