[WIP] FreeCAD's websites improvements initiative - Step 1 : Homepage and blog migration

[marcuspollio]

Nota bene: this issue is work-in-progress, more content will be added or changed following provided feedback

TL;DR

The gist of this first step of the websites improvements initiative is to prepare the Homepage and the Blog for the coming release of version 1.0 with a new, easier to maintain, documented and more accessible and welcoming website, using the common platform (the static site generator Hugo).

Context

FreeCAD's websites infrastructure has been developed organically over the years. It is made up of various parts which interact differently both for the end-user and the content contributor. Moreover they do not communicate easily with each other, they do have a different logic data-wise and incoherent visual designs. All this contributes to a problematic maintenance and is not advantageous for the project's impact. However, there are a number of positive qualities to be retained from the present state, which can serve as useful references for any improvement.

Early 2024, an initiative was launched by some Design Group contributors to review and improve the situation. This is the first step in a multi-year initiative.

This step has two simultaneous objectives : update the most crucial parts of the infrastructure in preparation for the release of FreeCAD 1.0, and lay the foundations for a set of guidelines and documentation for the websites infrastructure and maintenance.

Problems

Linked issues

Requirements

Note that this is a subjective appreciation, no strict criteria have been used.

+++ indicates a high importance or a high fulfillment (works great)

++ indicates a medium importance or a medium fulfillment (works ok)

+ indicates a low importance or a low fulfillment (works poorly)

General

Requirement	Importance for FreeCAD websites	Current Homepage implementation	Current Blog with WordPress	Unification with Hugo SSG
Type	does not apply	custom dynamic website without database	dynamic CMS with database	static site generator
Softwares and frameworks	does not apply	Bootstrap, jQuery, PHP, Crowdin	PHP, MySQL/MariaDB	Go, JAMStack
License	+++ most free and open possible	++ MIT and proprietary (Crowdin)	+++ GPLv2	+++ Apache 2.0
Development model	+++ open or community-based	++ Community and private company (Crowdin)	+++ WordPress Foundation and community	+++ Community
Timeline	+++ long established and long-term support	++ 19-77% all web, >12 years, unknown (Crowdin)	+++ 43% all web, >20 years	+++ 11 years
Software cost	+++ free of charge or moderate price	+++ free, free for non-commercial Foss (Crowdin)	+++ free, most plugins are free	+++ free, most themes are free
Accessibility	+++ most devices and languages	++ possible but implementation lacking	+++ extensive guidelines and tools	+++ extensive guidelines and tools
Performance	++ efficient and low bandwidth	++ simplicity helps with speed, images make it slow	++ needs database queries, but caching can help	+++ very fast, simplicity helps, images preprocessed
Security	+++ most secure and reliability	++ needs lib updates and some knowledge	++ core secure if updated, attention to plugins !	+++ quite secure, specially with no JS

Workflow

Requirement	Importance for FreeCAD websites	Current Homepage implementation	Current Blog with WordPress	Unification with Hugo SSG
Content management	+++ most WYSIWYG for low barrier of entry	++ needs a bit of HTML/CSS know-how	+++ integrated Gutenberg block editor	++ needs a bit of Markdown know-how
Medias management	+++ most WYSIWYG for low barrier of entry	++ needs a bit of HTML/CSS know-how	+++ integrated Gutenberg block editor	++ needs a bit of Markdown know-how
Blog posts support	+++ integrated with filters	+ possible but not in current form	+++ main "raison-d'être"	+++ main "raison-d'être"
Translations management	++ translation in context	++ not in full context, requires Crowdin and scripts	++ needs a dedicated plugin, see below	++ needs some setup, but then easy
Style management	++ easy adjustments while customisable	++ needs a bit of HTML/CSS know-how	+++ themes and templates	+++ themes and templates
Revision control	++ git integration for changes follow-up	+++ git for all files, continuous deployment	++ git for wp-content, continuous deployment	+++ git for all files, continuous deployment
Deployment	++ easy dev > staging/testing > prod setups	++ needs a bit of git know-how	++ needs a bit of git know-how	++ needs a bit of git know-how
User accounts management	++ single easy and secure system	does not apply	++ user management with roles in wp-admin	does not apply, can have authors data files
Maintenance and debugging	++ status, admin functions, setup, backups	++ no easy maintenance access, backups via git	++ many status, admin, backup tools	++ setup needed, backups via git

Scalability

Requirement	Importance for FreeCAD websites	Current Homepage implementation	Current Blog with WordPress	Unification with Hugo SSG
Extensibility and integration	++ large existing possibilities and reusability	++ needs development, but no real limits	++ large ecosystem and examples	++ needs development, large ecosystem, but no real limits
Plugins	++ extensive choice, easy setup, support	does not apply	++ large choice, setup and support variable	++ front-end framework or headless CMS possible
Custom	++ ability to accommodate custom solutions	++ needs development, but no real limits	++ using WordPress hooks	++ using Go modules

Proposal

• Make the Homepage and the Blog work together, on the same platform (Hugo) with a similar workflow used FreeCAD-wide (Pull Requests to the Git repositories, here with Markdown files) . This way, the Blog becomes really part of the main website, and not a additional different body (is this ringing any bell ?) This allow to reuse some of the already existing content (converted to Markdown files) while deprecating separated and cumbersome maintenance parts (the present Homepage and the Blog) .
• Develop a simple to use design that promotes the FreeCAD project efficiently, for the version 1.0 release and the future. Every page or external link should be accessible in 3 clicks at most (ideally 2 for the most used ones). The experience should be on-par for every language and device (desktop, mobile, etc.). Also take the opportunity to improve the donation pages and provide a pleasant space for release notes.
• Set some simple documentation for content contributors to the new unified website (blog posts, translations, medias, texts), while providing a deeper access to experienced contributors (web developers and admins) to tweak advanced features (theme, templates, config, etc.). Instructions for managing the different environments (development, testing, production) and version-control are included. Guidelines to ease maintenance, workload and prevent security issues are included. A references section and a list of contacts within the FreeCAD project (admins, editors, translators, etc.) to welcome new contributors are also included.
• Setup simple and efficient Testing and Production environments with Continuous Integration and Continuous Deployment. For Testing directly on the repository with GitHub Pages and for Production on the dedicated web server.

Design

Structure

├─ Homepage ├─ Features ├─ Download ├─ Releases ├─ News ├─ Documentation ├─ Community ├─ Contribute ├─ Donate └─ About

WIP mockups

Homepage

Features Page

Download Page

Release Notes Page

News Page

Deliverables

• The completed and validated design, before the implementation begins.
• The base of documentation and guidelines, to be improved while the site is implemented.
• The website migration bringing together the Homepage and the Blog, with previous content or placeholders for future content additions.
• A new repository for follow-up tasks, issue reports and improvements.

Resources

The design and development work is mainly carried out by marcuspollio, with inputs and feedback from the Design Group (mainly Max, JigglyBuff , Obelisk, Mistermaker, Kadet, Alex) and some maintainers (Chris and Kurt). Some of them have offered to do code review, testing or content contributions. Translators have not been formally contacted at this time. A larger request for content (texts, illustrations, video, example files, etc.) will be made after the first deliverable is completed.

Indicative timeline

• Complete this design task and incorporate feedback : from May to mid-June
• Setup of a development environment : from May to mid-June
• Feature Freeze of FreeCAD : 3 June
• Content contributions request (texts, illustrations, video, files, etc.) : from early August
• Documentation and guidelines draft : from early June to end of July
• Migration of the new unified website in a testing environment with GitHub Pages : from mid-June to end of July
• UI Freeze of FreeCAD : 24 June
• Selection of contributed content and its addition to the website : from mid-August
• Testing and improvements of the new unified website : from early August
• Cleanup of the present Blog database (posts, tags, user accounts, etc.) : from early August
• Backup of the present Blog database, conversion to Markdown files and addition to the new unified website : early August
• Request for translations and their addition to the website : from end of August
• Finalization of the documentation and guidelines : end of August
• Setup of the final production environment of the website : mid-September
• Buffer time for last-minute finishing touches : from end of September
• Release of the new unified website : with the release of version 1.0 of FreeCAD (between October and end of 2024)

Questions

• more to be added soon