Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Upgrade Docusaurs Version and Add Integration Tests #491

Open
5 tasks
gemanor opened this issue Jan 21, 2025 · 40 comments
Open
5 tasks

Upgrade Docusaurs Version and Add Integration Tests #491

gemanor opened this issue Jan 21, 2025 · 40 comments
Assignees
@asr2003
Labels
💎 Bounty

Comments

@gemanor
Copy link
Collaborator

gemanor commented Jan 21, 2025 •
edited
Loading

Details

We want to upgrade the Docusaurus version of the docs to the latest stable version - 3.7

To ensure the quality of the upgrade, this task contains the following subtasks:

Bounty Assignment

  1. Before participating in this bounty, Please comment with your detailed plan and timeline. We will not assign this issue if this information is missing.
  2. Because of the complexity of this task, we will have to choose the assigned contributor based on their experience in the domain. It will not be on a first-come, first-served basis. After the upgrade, we will open some other easiest bounties for beginners.
@algora-pbc Algora PBC
Copy link

algora-pbc bot commented Jan 21, 2025 •
edited
Loading

💎 $250 bounty • Permit.io

Steps to solve:

  1. Start working: Comment /attempt #491 with your implementation plan
  2. Submit work: Create a pull request including /claim #491 in the PR body to claim the bounty
  3. Receive payment: 100% of the bounty is received 2-5 days post-reward. Make sure you are eligible for payouts

Thank you for contributing to permitio/docs!

Add a bounty • Share on socials

Attempt Started (GMT+0) Solution
🟢 @onyedikachi-david Jan 21, 2025, 11:09:11 AM WIP
🟢 @asr2003 Jan 21, 2025, 11:58:47 AM WIP
🟢 @AliYar-Khan Jan 21, 2025, 12:12:53 PM WIP

@onyedikachi-david
Copy link

onyedikachi-david commented Jan 21, 2025 •
edited by algora-pbc bot
Loading

/attempt #491

Algora profile Completed bounties Tech Active attempts Options
@onyedikachi-david 14 bounties from 7 projects
TypeScript, Python,
JavaScript & more
Cancel attempt

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 21, 2025

Hey @onyedikachi-david , thanks for considering this issue,
Please read the requirement, and share example for your experience with such issues and your detailed plan and timeline for it

@asr2003
Copy link
Contributor

asr2003 commented Jan 21, 2025 •
edited
Loading

Hello @gemanor,

I would like to get assigned and work on this task. Below is my detailed plan and timeline for upgrading Docusaurus to version 3.7 and implementing integration tests

Plan

  1. Upgrade Docusaurus (Day 1)
    Here I will update package.json to change the versions of @docusaurus/core and @docusaurus/preset-classic to 3.7.0 and check for any immediate errors or warnings during installation.

  2. Compatibility Check (Days 2-3)
    We can review the compatibility checklist provided in the Docusaurus documentation or changelog to identify any breaking changes or compatibility issues. Then we can address this issues by making necessary code adjustments

  3. Implement Playwright Tests (Days 4-6)
    Here I will set up Playwright in the project and will create a script to iterate over sitemap.xml, taking screenshots of each page.
    Then we can ahead to integrate visual regression testing with Argos as per the provided instructions

  4. Fix All Failed Tests (Days 7-8)
    Here we will run the Playwright tests and identify any failures, debug and fix issues to ensure all tests pass successfully.

  5. Configure CI in .github (Day 9)
    I will add the necessary configuration files in the .github folder to run tests automatically on push and pull requests to ensure that the CI pipeline includes steps for running Playwright tests

For my experience during my undergraduate summer internship last year at Mindtree, I worked with Docusaurus to build and maintain internal documentation sites. This included tasks such as upgrading versions, resolving compatibility issues and refactor for the overall quality of the documentation platform.

@asr2003
Copy link
Contributor

asr2003 commented Jan 21, 2025 •
edited
Loading

/attempt #491

Algora profile Completed bounties Tech Active attempts Options
@asr2003 9 bounties from 4 projects
Typescript, Rust,
Go & more
Cancel attempt

@AliYar-Khan
Copy link

AliYar-Khan commented Jan 21, 2025 •
edited
Loading

Project Goals

  1. Upgrade the site to Docusaurus 3.7 and resolve compatibility issues.
  2. Implement visual regression testing with Playwright and Argos for quality assurance.
  3. Ensure a fully automated CI pipeline with Playwright tests integrated.

Detailed Plan

1. Upgrade to Docusaurus 3.7

  • Task: Upgrade Docusaurus and all dependencies to the latest stable version.
  • Steps:
    • Update docusaurus.config.js and other project configuration files if necessary.
    • Install updated dependencies via npm or yarn.
    • Verify the build process runs without errors.
  • Deliverables:
    • Running version of the site with Docusaurus 3.7.
  • Estimated Time: 2 days

2 Compatibility Check

  • Task: Go through the Docusaurus compatibility checklist and address any issues.
  • Steps:
    • Review breaking changes and deprecated APIs.
    • Update code to use new APIs or configurations.
    • Test the site locally to identify rendering or functionality issues.
  • Deliverables:
    • Compatibility checklist with resolved issues.
    • No functional or visual errors on the local build.
  • Estimated Time: 3 days

3. Implement Playwright Tests

  • Task: Set up Playwright to iterate over sitemap.xml, take screenshots of all pages, and compare them with Argos.
  • Steps:
    1. Install Playwright:
      • Add Playwright and related dependencies to the project.
    2. Create Tests:
      • Write a script to parse the sitemap.xml and navigate to all listed pages.
      • Capture screenshots and upload them to Argos for visual comparison.
    3. Test Execution:
      • Run the Playwright script locally and review initial results.
  • Deliverables:
    • A Playwright script for automated screenshot testing.
    • Argos setup linked with the project repository.
  • Estimated Time: 4 days

4. Fix Failed Tests

  • Task: Address all failed visual regression tests and other quality issues.
  • Steps:
    • Analyze failed Argos tests to identify discrepancies.
    • Fix layout, styling, or rendering issues causing the failures.
    • Re-run tests to verify fixes.
  • Deliverables:
    • All tests pass without any visual differences.
  • Estimated Time: 3 days

5. CI Configuration

  • Task: Integrate Playwright tests into the CI pipeline.
  • Steps:
    • Create a CI workflow file in the .github folder.
    • Add Playwright and Argos tests as part of the CI pipeline.
    • Configure the pipeline to run on every pull request or push to specific branches.
  • Deliverables:
    • Fully automated CI pipeline for Playwright tests.
    • Documentation on how the pipeline works.
  • Estimated Time: 2 days

6. Final Testing and Review

  • Task: Perform final testing and project-wide review.
  • Steps:
    • Test the upgraded site on various browsers and devices.
    • Collect feedback from the team for any additional fixes.
  • Deliverables:
    • Finalized and stable site running Docusaurus 3.7.
  • Estimated Time: 1 day

Timeline

Task Start Date End Date Duration
Preparation Day 1 Day 1 1 day
Upgrade to Docusaurus 3.7 Day 2 Day 3 2 days
Compatibility Check Day 4 Day 6 3 days
Implement Playwright Tests Day 7 Day 10 4 days
Fix Failed Tests Day 11 Day 13 3 days
CI Configuration Day 14 Day 15 2 days
Final Testing and Review Day 16 Day 16 1 day

Project Duration

16 days (approximately 2.5 weeks)

Key Deliverables

  1. Upgraded Docusaurus version 3.7 with resolved compatibility issues.
  2. Playwright tests for visual regression integrated with Argos.
  3. Fully automated CI pipeline ensuring quality and stability.
  4. Documentation on the upgrade process and CI setup.

/attempt #491

Options

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 22, 2025

I'm assigning it to @asr2003 as he made the first proposal that make the most sense for the plans here.

@asr2003 please keep a cadence of updates every two days so we can track the progress 😃

@ologbonowiwi
Copy link

Quick suggestion: Per earlier contributions in another project and other experiences, it would be great to start this with Playwright + Argos, possibly.

This way, we can ensure all tests pass at least once, breaking up the dependency between the CI/framework setup/tests themselves and dependencies.

While it's feasible and pretty much ok, testing earlier would maybe have higher confidence when migrating.

Note that this is only a suggestion from a fellow contributor, and I'm not affiliated with the project in any way, so it's more general advice and not a must.

Also, I am open to contributing to the automation test/ci part if you feel comfortable with it @asr2003

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 23, 2025

Hey @ologbonowiwi , your suggestion make sense to me. I hope that @asr2003 will collaborate with you on that.
Also, if he will not response with his availability until EOD, I'll assign it to you. I'll just need a clear timeline that was missing in your suggestion

@asr2003
Copy link
Contributor

asr2003 commented Jan 23, 2025

@gemanor I have already started working on it

@AliYar-Khan
Copy link

I have made all the necessary changes to packages and also the mdx files are getting compiled now. But docusaurs is causing issue when building the whole project.

@gemanor @asr2003

@ologbonowiwi ologbonowiwi mentioned this issue Jan 23, 2025
Open
@ologbonowiwi
Copy link

hey guys, I had some wip of the tests and decided to proceed (never worked with argos before and it seemed fun), so I added the integration tests stuff on #492

@asr2003
Copy link
Contributor

asr2003 commented Jan 25, 2025

@gemanor To update progress, I have updated and fixed few issues encountered after update in codebase

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 25, 2025

Thanks, @ologbonowiwi, I'll take a look on the PR tomorrow (although this PR assigned to @asr2003)

@asr2003 you mean updated to 3.7 with tests+Argos? Can you share the WIP PR please?

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 26, 2025

@asr2003 when running the Playwright tests and taking screenshots, you can skip all the pages from version 1.0.0 as they are in end of life

@gemanor gemanor mentioned this issue Jan 26, 2025
Open
@gemanor
Copy link
Collaborator Author

gemanor commented Jan 27, 2025

Hey @asr2003 - please update your progress with a draft PR by today's EOD so we can keep you assigned to this issue

@asr2003
Copy link
Contributor

asr2003 commented Jan 27, 2025

Sure!

@asr2003
Copy link
Contributor

asr2003 commented Jan 27, 2025 •
edited
Loading

@gemanor Can you confirm this issue is with me or with you too??
While I had ran yarn 

[4/4] Building fresh packages...
[-/5] ⢀ waiting...
[2/5] ⢀ core-js-pure
[-/5] ⠠ waiting...
[-/5] ⠠ waiting...
error C:\Users\91970\desktop\asr\permitio-docs\node_modules\@untitaker\hyperlink: Command failed.
Exit code: 1
Command: node ./install.js
Arguments:
Directory: C:\Users\91970\desktop\asr\permitio-docs\node_modules\@untitaker\hyperlink
Output:

Installation is failing. But it worked before I have cleaned it and installed freshly and i am hitting this issue today

@ologbonowiwi
Copy link

While I had ran yarn

prob safer to run npm ci or npm install. the project has only package-lock.json so I assume it's the default package manager

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 27, 2025

We are using npm for installation here

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 27, 2025

And all works fine

@asr2003
Copy link
Contributor

asr2003 commented Jan 27, 2025

@gemanor From README I used the yarn and it got messed up i guess then. I need to switch back to npm again and build and test my changes.

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 27, 2025

Okay. Please share the PR draft when you have it.

@asr2003
Copy link
Contributor

asr2003 commented Jan 27, 2025 •
edited
Loading

@gemanor Could I know the specific node and npm versions to use? It hitting the build issues to start with npm of asking incompat npm and node versions

Edit: Worked now after few experiments with versions

UPDATE: There are two major migrations here MDX to v3 and react to 18. I have successfully fixed MDX and migrating react. Once this done I will draft PR

@filipermit
Copy link
Collaborator

Thanks @asr2003 - Please let us know when you have a PR ready.

@gemanor
Copy link
Collaborator Author

gemanor commented Jan 29, 2025

@asr2003 any estimations for the Draft PR?

@asr2003
Copy link
Contributor

asr2003 commented Jan 29, 2025

@gemanor I have messed up when I have upgraded all once. Errors are emitted like rabbithole and now I have the went in a structured approach first upgrading prerequisites. I am opening draft shortly with prerequisites updates of MDX (v2 -> v3) and React18

@ologbonowiwi
Copy link

ologbonowiwi commented Feb 4, 2025 •
edited
Loading

Hi guys, since we haven't received any updates on it, @gemanor, can you look at #492?

I want to work on this, but I'm waiting for your review of my PR.

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 6, 2025

Hey, @ologbonowiwi , most of our discussion is in the PR created by @asr2003 - take a look at #499

@ologbonowiwi
Copy link

I honestly don't mind on not getting the bounty for #492, but unless we merge the argo thing before the update (feel free to open your version only with argos @asr2003, since you were assigned anyways and you have almost the same done on your side), we'll not be able to actually verify that the app is rendered in the same way, since we won't have current version to check against (as the first run will be on the new version 😅).

Also, one find I had running Argos a few times and having a working dashboard on my fork: video elements are bjorked. since the screenshot is taken as soon as the page loads, the video is not loaded yet, and the spin is always in different positions. this makes the tests flaky and generates unnecessary checks. we'd be better of changing css of videos to visibility: hidden. is what I did on #492.

The same can also be seen on @asr2003 Argos dashboard, here: https://app.argos-ci.com/asr2003/permitio-docs/builds/6/133925369

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 11, 2025

Thanks for the comments and direction here, @ologbonowiwi! Super appreciated!

@asr2003 can you address the points he brought here?

@asr2003
Copy link
Contributor

asr2003 commented Feb 11, 2025

@gemanor Yes, it's better if we first merge only argo part so that we can have clear view of changes through upgrade breaking changes from stable version

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 13, 2025

Left a comment in the PR, please open a PR for only this step (no upgrades), and after it will pass we will merge it

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 16, 2025

Hey, @asr2003 , can you address the comments from me and @ologbonowiwi in the Argos PR so we can merge it?

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 17, 2025

@asr2003 - as we merged the Argos, let's now focus on the upgrade. Please share the timeline when you have jt

@asr2003
Copy link
Contributor

asr2003 commented Feb 18, 2025 via email

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 19, 2025

Looking forward to it :)

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 20, 2025

Hey, @asr2003 , we are after time here and looking to do the upgrade ASAP. Is there any news with your implementation, or can we assign it to someone else?

@asr2003
Copy link
Contributor

asr2003 commented Feb 21, 2025 via email •
edited
Loading

@gemanor
Copy link
Collaborator Author

gemanor commented Feb 23, 2025

I am looking forward to this progressing. Is it the same problem you described in the draft PR?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@asr2003 asr2003

Labels
💎 Bounty
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@gemanor @AliYar-Khan @onyedikachi-david @ologbonowiwi @filipermit @asr2003