GSoD Workspace: Reorganize the contributor guide of WasmEdge

[adithyaakrishna]

Project

• Title: Reorganize the contributor guide of WasmEdge
• Description: This project aims to create a contributor guide for WasmEdge to help new contributors develop plug-ins. The project involves reviewing the existing documentation and creating new guides and references for the C, C++, and Rust plug-in SDKs. The project will also update the documentation on the new Docusarus-based site, wasmedge.org/docs/. The required content for the contributor guide includes an architectural overview, getting started with contributing, building WasmEdge, testing WasmEdge, fuzzing, building a plug-in, reporting an issue, and proposing a feature request.

Detailed Description:

• Review existing documentation: The first step is to review the existing contributor documentation to identify gaps and improvement areas. This will involve understanding the current documentation structure and content, identifying any outdated or irrelevant information, and making notes on what needs to be updated or added.
• Create an outline: Based on the review, create an outline for the new contributor guide. This outline should cover all the required content mentioned above, with clear headings and subheadings that make it easy for new contributors to navigate and find the information they need.
• Develop new guides and references: For each section of the outline, create new guides and references that provide clear, concise, and actionable information for new contributors. This will involve researching best practices for each topic, providing step-by-step instructions where necessary, and using clear language and visuals to make the information easy to understand.
• Update the documentation: Once the new guides and references are complete, update the documentation on the new Docusarus-based site, wasmedge.org/docs/. This will involve creating new pages for the contributor guide, linking to relevant sections of existing documentation, and making sure that the new content is integrated seamlessly with the existing site design and structure.
• New Features: Add a search field to the documentation through, https://docusaurus.io/docs/search such that users and visitors of the site can easily access the information that they need without going through the whole website.
• Test and refine: Finally, test the new contributor guide with a group of new contributors to identify any remaining issues or areas for improvement. This feedback can be used to refine the guide and make it as effective as possible for new contributors.

Overall, the key to tackling this problem is to focus on creating clear and actionable information that is easy for new contributors to understand and use. By taking a structured approach to review, outlining, developing, and testing the new contributor guide, it should be possible to create a valuable resource that helps WasmEdge attract and retain new contributors.

Project Details

• Contributor: @adithyaakrishna
• Mentor: @yiying, @juntao, @alabulei1

How does it help?

• Easier Project Management
• Clearer Communication
• Maintaining Consistency
• Easier Transfer of Knowledge
• Easier Project Evaluation

Milestones

• [x] Setup basic CI and CD | Migrate to TS
• [x] Upgrade Docusaurus and Add Workflows
• [x] Add Linting Capabilites and Build Checks
• [ ] Add Netlify which requires mentors' admin permissions
• [x] Gather Information and Expectations from Mentors
• [x] Gather information from books site to be migrated to docs site
• [x] Migrate books site to docs site.
• [ ] Improve SEO
• [x] Remove Old Docs from https://github.com/WasmEdge/WasmEdge/tree/master/docs/book
• [x] Gather content to be updated across the new docs site
• [ ] Work with mentors to add new content for the contribution guide
• [ ] Work with mentors to add new content to the docs site
• [ ] Add versioning capability to the project

Detailed Outline

• Review PRs related to Docs changes: Collaborate with reviewers to review and provide feedback on PRs related to documentation changes in the WasmEdge project.
• Theme customization: Change the overall theme of the Docusaurus site to align with the WasmEdge project colors, ensuring a consistent visual identity.
• Contribution Guide for WasmEdge projects: Collaborate with mentors to create a comprehensive contribution guide for WasmEdge projects. Include the following sections in the contribution guide:
  • Getting started with the project
  • Cloning/Forking the project
  • Local setup
  • Contribution workflow
  • Creating PRs and working on requested changes
  • Documenting new features
  • Testing and fuzzing
• Contributor Guide Outline:
  • Architectural overview
  • Getting started with contributing
  • Building WasmEdge
  • Testing WasmEdge
  • Fuzzing
  • Reporting an issue
  • Proposing a feature request
• Enhancements to Documentation:
  • Add a Bots page to inform users about the bots used in the WasmEdge community.
  • Incorporate screenshots and images to make the documentation more visually appealing, particularly in sections with lengthy text-based content.
  • Include flowcharts or architecture diagrams to enhance the visual clarity of the documentation.
  • Update the landing page to improve user understanding and navigation.
• Standardization and Compliance:
  • Add Contributing guides, License, and Code of Conduct to all WasmEdge projects, aligning them with CNCF Standards.
  • (Optional - Extended Scope) Add Interactive Video for the whole contributing flow.
• Netlify Setup and Streamlined Workflow: Work with mentors and reviewers to set up Netlify for deploy previews, enabling a streamlined process for merging MRs related to documentation changes. (@alabulei1 Would need your help with this)
• GitHub Actions and Automation:
  • Implement new GitHub actions to automate the labeling of PRs and issues, reducing the workload of maintainers.
  • Ensure that any content changes trigger the CI workflow, excluding the readme.md file.

Progress

• Pre-GSoD Tasks - Before May 10th 2023 - https://github.com/WasmEdge/docs/issues/93#issuecomment-1577926246
• GSoD Period - May 10th to May 22nd 2023 - https://github.com/WasmEdge/docs/issues/93#issuecomment-1577932620
• GSoD Period - May 23rd to June 10th 2023 - https://github.com/WasmEdge/docs/issues/93#issuecomment-1577932620
• GSoD Period - June 11th to June 27th - https://github.com/WasmEdge/docs/issues/93#issuecomment-1591563360
• GSoD Period - June 27th to July 10th - https://github.com/WasmEdge/docs/issues/93#issuecomment-1618866558

[adithyaakrishna]

Pre-GSoD Tasks - Before May 10th 2023

Description: Summary of all the work done before official GSoD period. This includes broken link fixes, spell check issues, adding new workflows. This may also include some tasks mentioned in the above proposal.

• https://github.com/WasmEdge/docs/pull/16
• https://github.com/WasmEdge/docs/pull/18
• https://github.com/WasmEdge/docs/pull/19
• https://github.com/WasmEdge/docs/pull/30
• https://github.com/WasmEdge/docs/pull/38
• https://github.com/WasmEdge/docs/pull/58
• https://github.com/WasmEdge/docs/pull/59
• https://github.com/WasmEdge/docs/pull/60

[adithyaakrishna]

GSoD Period - May 10th to May 22nd 2023

Description: Summary of work done in the first phase of the timeline for the official GSoD period.

Expected Outcome:

• [x] Add linting features, coordinate with mentors to add netlify CI.
• [x] Migrate Docusaurus JS to TS based project

Issues & PRs

• https://github.com/WasmEdge/docs/pull/80
• https://github.com/WasmEdge/docs/pull/72
• https://github.com/WasmEdge/docs/pull/69
• https://github.com/WasmEdge/docs/pull/67
• https://github.com/WasmEdge/docs/pull/66
• https://github.com/WasmEdge/docs/pull/74
• https://github.com/WasmEdge/docs/issues/90
• https://github.com/WasmEdge/docs/issues/92

[adithyaakrishna]

GSoD Period - May 23rd to June 10th 2023

Description: Summary of the work done in the Porting of Old Docs Phase - P1 for the official GSoD period.

Expected Outcome:

• [x] Make a list of missing content
• [x] Make a list of content redirections
• [x] Work with @alabulei1 to finish off https://github.com/WasmEdge/WasmEdge/pull/2541

Missing Content and Redirections List - https://gist.github.com/adithyaakrishna/f19d65263cd4db7701b39676f774ab62

[alabulei1]

Your list is great. Much appreciated. @adithyaakrishna

I can provide a detailed list of the content that has been missed and updated. See details here: https://docs.google.com/document/d/1wYOLvhuWt50M0sMPGN2TlA5JMICzv5BSczPmV4GsilQ/edit?usp=sharing

This is helpful when you migrated the new content from the old book. Let me know if you have any questions.

[adithyaakrishna]

GSoD Period - June 11th to June 26th

Description: Summary of the work done in the Porting of Old Docs Phase - P2 for the official GSoD period.

Expected Outcome:

• [x] Remove Unnecessary or Unwanted Docs
• [x] Add note across old docs to say about content migration

Issues & PRs

• https://github.com/WasmEdge/docs/issues/94
• https://github.com/WasmEdge/WasmEdge/pull/2593
• https://github.com/WasmEdge/docs/pull/109
• https://github.com/WasmEdge/docs/pull/111
• https://github.com/WasmEdge/docs/pull/113

[adithyaakrishna]

@alabulei1 I just went through the same and it looks good to me as well! I will make sure to add them as well when working on the migration part :)

[alabulei1]

Hi @adithyaakrishna

WasmEdge 13.0 is released last week. One of the most important features is the unified CLI, so we should update the CLI docs on the new docs.

But there is no upcoming PRs in the last two weeks. May I ask you to update the CLI docs as soon as possible? Without corresponding docs, we can't promote the latest release to the community. Thanks.

[adithyaakrishna]

GSoD Period - June 27th to July 15th 2023

Description: Summary of the work done in the Porting of Old Docs Phase - P3 for the official GSoD period.

Expected Outcome:

• [x] Migrate old content from Books to Docs
  • [x] Part - 1
  • [x] Part - 2
• [x] Added Eslint Parser for MD Files

Issues & PRs

• https://github.com/WasmEdge/docs/issues/120
• https://github.com/WasmEdge/docs/issues/133
• https://github.com/WasmEdge/docs/pull/125
• https://github.com/WasmEdge/docs/pull/126
• https://github.com/WasmEdge/docs/pull/124
• https://github.com/WasmEdge/docs/pull/131
• https://github.com/WasmEdge/WasmEdge/pull/2644
• Adds Eslint Parser for MD - 51cf778

Note: Work was paused for a brief period due to refactoring of docs - https://github.com/WasmEdge/docs/pull/135

[adithyaakrishna]

GSoD Period - July 15th to August 30th

Description: Summary of the work done in the Porting of Old Docs Phase - P4 for the official GSoD period.

Expected Outcome:

• [x] Remove content from old docs - Split into two parts
  • [x] Removal of Chinese Docs
  • [x] Removal of English Docs and Redirection
• [x] Improve SEO
• [x] Remove zh-tw content from https://github.com/wasmedge/wasmedge Repo
• [x] Optimize Images

Issues & PRs

• https://github.com/WasmEdge/docs/pull/141
• https://github.com/WasmEdge/WasmEdge/pull/2693
• https://github.com/WasmEdge/docs/pull/142
• https://github.com/WasmEdge/WasmEdge/pull/2709
• https://github.com/WasmEdge/docs/pull/145
• https://github.com/WasmEdge/WasmEdge/pull/2727

[adithyaakrishna]

GSoD Period - September 1st to Present

Description: Summary of the work done during new docs phase

Expected Outcome:

• [x] Reviewing PRs
• [x] Add docs for Fuzzing
• [x] Add comprehensive docs for Testing
• [x] Update Docusaurus
• [x] Add contributors page
• [x] Added Sitemap
  • [x] To main site
  • [x] To docs site
• [x] Added plugin links

Issues & PRs

• https://github.com/WasmEdge/docs/pull/181
• https://github.com/WasmEdge/docs/pull/179
• https://github.com/WasmEdge/docs/pull/177
• https://github.com/WasmEdge/docs/pull/175
• https://github.com/WasmEdge/www/pull/24
• https://github.com/WasmEdge/docs/pull/170

Note: Not much work was done during Sept 15th to Oct 13th due to some personal reasons and had to put this in writing here to be on the same page