🚀 - Add changelog inside the web application

[riccardoperra]

Description

Users should be notified when a new update of the app has been released. The idea is to handle a changelog component which will shows all info about the newest release.

Here's some recommendation/questions that we've discussed with @hackpirodev:

Dialog once you open the app

Guest users will see a full screen dialog with the latest release info the first time they see the page. (Then we will save a "user read" flag in the local storage in order to save this info locally.

For Authenticated users we may save this info using the Auth0 user metadata

How we retrieve the content

We have some ideas about how rendering the content of the release automatically:

• Notion Content Landing Page
• Github releases
• Save the content in our database/backend? We may have more control but Railway is not free 😄

Here are some things that we have to analyze in order to take the right way:

• We need to skip the patch/fixes releases or don't make them more priority than a more important release
• We need to handle the markdown / have some metadata in order to display "title",. "thumbnail", "small description", "full description". Can we group these in order to show a grouped content? (e.g. Majors first, then minors inside it and all patches listed above)
• How can we know if there is a new release?
• How much this change impact in performance for bundle size, fcp/lcp (lighthouse) scores?

How to display this content in the website

• We need a new page on the upcoming website (e.g. https://changelog.framer.website/)

How we render the content

In my opinion MDX could be the right choice since there are some examples of using solid with mdx content
in order to also have more flexibility (what if we need to render some custom content inside?)

In the case we choose Notion, we have to make sure we can render his blocks without taking a lot of effort since there aren't libraries that does this job right now (there is an example for React https://github.com/splitbee/react-notion) but implementation could be easier without VDOM

cc @hackpirodev

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[hackpirodev]

@riccardoperra

Summary

Considering we need the same content as the changelog for codeimage and for the landing page it's necessary to start from the creation, as totally different. Todo releases notes I think we have two ways:

1. Internal tool (with UI) to create release notes using GH's API, to have a skeleton bootstrap with notes taken from changelogs and have an MD editor to change and other stuff. These releases need DB to save them and have their state(like draft, published). But when we retrieve the list I prefer if this page builds static, to not have expenses for each get.

2. CI from the terminal with the command create release notes, for example:
   changelog -create --type='patch|minor|major...'this retrieve the list changelog from gh and we can pick one. Then ci then create a release note using this info as a base to create a new post in notion with label draft and the selected type.
   Then we can use notion to edit our changelog and when it's ready to publish we can add the label as ready.
   In terminal changelog --publish If the command finds only one get this content and publish the release with GH api, and changes the label of notion from ready to published otherwise shows a list of notions with a label ready so we can pick the release to publish.

Considerations

As analysed both required no indifferent effort and deep dive to do better analysis. But to try one or another choice we can skip some steps and do it manually focusing on rendering the changelogs.

1. retrieve from DB and do the page statically abstracting data to render in in codeimage and landing
2. retrieve the changelog with GH's API and same as above do the page statically

[riccardoperra]

Creating an another ad-hoc tool in my opinion is not the good choice, the effort that we should take for having something working is a lot considering that we are not planning to release and update the change logs pretty often.

Also no one is stopping us to put the .md files in our repo in order to keep all changelog versioned with git.

having differences between GitHub Releases and our changelog is not bad at all

I like the idea of retrieving the list of change logs in CI, the problem is know when we have to reload the changelog.

If we put the .md file in our repository, we are able to trigger a GitHub action workflow in order to rebuild everything.

The next problem is the parsing and the rendering. There are some libraries that may help us to convert the Notion blocks in md files https://www.npmjs.com/package/notion-to-md, but are we able to render and parse md files right now?

I saw there are some libraries that render mdx with solid but I’m not convinced at all, I saw someone in discord that it’s using this library https://www.npmjs.com/package/marked but it’s only .md (but that could be our real case)

So in my opinion the flow could be:

• we store the .md files somewhere
• We can trigger at every deploy a script that paese the md files and convert into HTML nodes for solid-start website
• on the app we can make a fetch call to retrieve the md file and parse and render it (so this is a runtime)

[riccardoperra]

Also forgot this.

The release tab of GitHub now consist of tagging the version of the repository and I am trying to do a new release/tag for every deploy (patch, minor, fix).

The changelog that we can show to the users could be custom and have a very different structure (for example showing only “new features” instead of grouping by minor/patch/major etc.

Keeping the two things separated imo it’s better and easier to mantain

[hackpirodev]

@riccardoperra if we organize the tabs it's easier for us to main, totally agree. So for the next release, the ideal flow to release could be:

1. import from gh the releases to have the base. As to do actually where you select from releases to have help from GH
2. push the base release to Notion
3. edit the release note in Notion
4. push the release note to GH from Notion

I suggest rendering the release notes using the obtained from GH API, so we don't need to import old releases from GH to Notion. The Notion will use only as an editor.

To have the release pages asap I would start from the end by retrieving data and rendering it. (Important it's useful if the page will render static using the data from the API to not use many resources and the free tier from GH)

So to code this I'll proceed:

1° stage

• play with API to retrieve releases notes (abstracting the logic to reuse later)
• abstract content obtained data to render (maybe in store?)
• do the releases page (content to show in a moda)l for codeimage
• do the release page for the landing page

2* stage

• reuse abstract logic to retrieve releases to do ci commands
• play with notion API to push the release selected
• obtain notes from notion
• do with API GH a new release note

WDYT?

[riccardoperra]

@riccardoperra if we organize the tabs it's easier for us to main, totally agree. So for the next release, the ideal flow to release could be:

1. import from gh the releases to have the base. As to do actually where you select from releases to have help from GH
2. push the base release to Notion
3. edit the release note in Notion
4. push the release note to GH from Notion

I suggest rendering the release notes using the obtained from GH API, so we don't need to import old releases from GH to Notion. The Notion will use only as an editor.

To have the release pages asap I would start from the end by retrieving data and rendering it. (Important it's useful if the page will render static using the data from the API to not use many resources and the free tier from GH)

So to code this I'll proceed:

1° stage

• play with API to retrieve releases notes (abstracting the logic to reuse later)
• abstract content obtained data to render (maybe in store?)
• do the releases page (content to show in a moda)l for codeimage
• do the release page for the landing page

2* stage

• reuse abstract logic to retrieve releases to do ci commands
• play with notion API to push the release selected
• obtain notes from notion
• do with API GH a new release note

WDYT?

As we said on telegram, there will be two different changelog for CodeImage

• Changelog to versionate the software by Github
• Changelog for users.

The two changelogs will not be directly synchronized since we don't want to show in website and application everything but just the most important things.

Here's the solution that we discussed and we may try at the moment:

1. We write the content on Notion
2. For every deploy, we will trigger a script which will convert the Notion page into Markdown
3. Both application and website will render the static markdown which is generated at build time.