ohwr / ohwr.org

OHWR's website

Open Hardware Repository 🐧

A new website proposal for the Open Hardware Repository.

If approved, this website will be deployed to https://ohwr.org, replacing the current OHWR website.

The website is built with Hugo using the Bigspring Light theme.

Build 🔨

Requirements 📋

• Go >= 1.22.5
• Hugo (the extended edition) >= 0.129.0
• Python >= 3.12.3
• PyYAML >= 6.0.2
• Pydantic >= 2.9.2
• email-validator >= 2.2.0

Steps 👣

1. Clone the project

   git clone https://github.com/OHWR/ohwr.org.git

2. Go to the project directory

   cd ohwr.org

3. Build the website

   make build

   The website is stored in the public directory.

4. Serve the website

   make run

   To view the website, open the URL displayed in your terminal.

Test 🧪

Requirements 📋

• reuse >= 4.0.3
• wemake-python-styleguide >= 0.19.2
• yamllint >= 1.35.1
• checkmake >= 0.2.2
• markdownlint-cli2 >= 0.10.0

Steps 👣

1. Clone the project

   git clone https://github.com/OHWR/ohwr.org.git

2. Go to the project directory

   cd ohwr.org

3. Run the tests

   make test

Deployment 📡

The website is deployed to GitHub Pages with the GitHub Actions workflow defined in .github/workflows/deploy.yaml.

The workflow builds and deploys the website whenever a change is pushed to the master branch.

Code of Conduct 📜

Please review our Code of Conduct to understand the expectations for behavior within the project community.

Security Policy 🔒

For information on our security policy and reporting vulnerabilities, please check our Security Policy.

Contributing Guidelines 🚀

We welcome contributions! Before getting started, please read our Contributing Guidelines for information on how to contribute to the project.

ohwr.org's Issues

Buttons turn blue when opening a link in a new window

Landing page

The Landing page layout should be:

OHWR logo

Welcome message

Submit button

About section with picture, summary and Read More button

Carousel of featured projects

Latest news paginated with 3 news.

Modify the about page image

Add about page image from https://be-cem-edl.web.cern.ch/ohwr/graphics/fmc_nanofip_bgblack.png

Refactor news with taxonomies

Import 5 OHWR projects

For the demo we should import at least 5 projects from OHWR and render them in this new website.

These 5 projects are currently hosted in CERN gitlab, with the repo mirrored in OHWR and all information etc are available (only) in the OHWR wiki.

The projects are:

1. https://ohwr.org/project/spec and https://gitlab.cern.ch/be-cem-edl/fec/hardware-modules/spec
2. https://ohwr.org/project/svec and https://gitlab.cern.ch/be-cem-edl/fec/hardware-modules/svec
3. https://ohwr.org/project/fmc-adc-100m14b4cha and https://gitlab.cern.ch/be-cem-edl/fec/hardware-modules/fmc-adc-100m14b4cha
4. https://ohwr.org/project/fmc-delay-1ns-8cha and https://gitlab.cern.ch/be-cem-edl/fec/hardware-modules/fmc-delay-1ns-8cha
5. https://ohwr.org/project/fmc-tdc and https://gitlab.cern.ch/be-cem-edl/fec/hardware-modules/fmc-tdc-1ns-5cha

The first two are FMC carriers while the other three are FMC modules. It would be nice if when users look at FMC modules they would see a "works with" link that points to FMC carriers and vice versa.

Update 'Licenses' page

Currently the 'Licenses' page is filled with placeholder content and needs to be updated.

Define YAML file contents

Instead of separate documentation, this should be the file template itself, with good comments for every possible option

Add Licenses page

Add GitHub Actions workflow to build and deploy website

Use the GitHub Actions workflow proposed in the Hugo documentation to build and deploy the website on GitHub Pages:
https://gohugo.io/hosting-and-deployment/hosting-on-github/

Divide the deployment into staging and production:
https://gohugo.io/getting-started/configuration/

Implement project info page generator

Takes as input the YAML file and produces a Hugo page with the project description. For the demo, this will include:

• description (text, mandatory)
• some photos
• link to project (optional), repo and forum (optional)
• status/news
• labels

Improve categories and tags page

Add images to the list of categories and tags.
Use a frame around each category/tag, white with a light shadow.

Add issue template to submit a project

Meet the recommended community standards

To meet the recommended community standards, a project should have:

• Description
• README
• Code of conduct
• Contributing
• License (we use 2 so GitHub won't recognize them, but it's OK)
• Security policy
• Issue templates
• Pull request template

More information at Open Source Guides.

Detect broken links and send email notification

1. The compose tool should read the internal and external configuration for each project and detect broken links before generating content.
2. The links to validate are: repository URL, website URL, image URLs, documentation URL, issue tracker URL, latest release URL, forum URL, news feed URL and extra link URLs.
3. If a broken URL is detected an email to the OHWR managers' mailing list is sent.
   • Which email account OHWR will send emails from?
   • Where will the managers' mailing list be created? CERN e-groups? If OHWR is not part of CERN it might make sense to create a mailing list elsewhere.
4. The content for a project with broken links is still generated and the OHWR managers decide what to do on a case-by-case basis, e.g. notify the project maintainer with a 30 day notice to fix the issue before the project is removed from OHWR.

Update 'Submit Project' page

1. Add instructions on where to search for existing categories before submitting a project.
2. Add instructions on how to request a new category: a name and a description should be provided.

Add bages to the project page

Create 'FAQ' page

A list of OHWR related FAQs.

Implement a basic static analysis to validate YAML files before using them and run it in CI

The tool should at least check that:

1. the syntax is valid
2. the mandatory options are there
3. no unknown options are provided
4. all URLs are accessible

Remove 'Help' and 'Members' footer links

The 'Help' and 'Members' pages don't exist and the links return 404.

Add Hugo page from a theme

Choose a Hugo theme from here: https://themes.gohugo.io/

Remove tags

Categories and tags are redundant, therefore we keep only the categories.

Properly licence all work in this repo and add REUSE linter in CI

And perhaps reuse badge in readme.

Implement static part of demo website

This includes:

1. landing page with logo, banner and background image
2. link to project list
3. info about OHL
4. search projects, also using labels
5. about
6. contact (no need to actually send emails)

Add About page

Add compatibility relationships

Project pages should contain a list of projects their are compatible with:

1. Introduce an optional compatible_projects field to each project in the config.yaml file that accepts a list of names of compatible projects.
2. The projects should be listed in vertical cards like in the 'Projects' section.
3. Only one project needs to claim to be compatible with another and compatibility is displayed in both project pages.
4. Project maintainers request the compatibility relationships by listing the compatible projects in the project submission issue.
5. OHWR maintainers will be responsible for confirming the validity of the compatibility relationship by contacting the maintainers of the projects claimed to be compatible before finalizing the association.

Refactor layout

Move as much as possible to the bigspring-light template upstream. Including the search functionality.

Unite project images and gallery at the top of project page

Parallelize the generation of content

The composer tool should generate the contents for each project in parallel.

Make spacing between project description and banner of links consistent

[PROJ] Add Flux Capacitor

URL of the project's git repository
https://github.com/vascoguita/TimeMachine_FluxCapacitor.git

Name of the project owner
Quentin Tarantino

Email address of the project owner
[email protected]

Build and deploy website via CI/CD

Optimize build GitHub Action

The build GitHub Action is installing all of the Python dependencies but only pydantic and PyYAML are required to build the website.

Display all the featured projects in a carousel

Add pytest unit tests

Test compose with pytest.

Open external links in a new window

Implement News

Each Project has its own set of news and the Home page should aggregate the latest news of all projects

Featured projects doesn't resize well on small sreens

Featured projects on the landing page in mobile phone mode don't show project names, summaries, etc...
In the projects page, the featured ones appear smaller and also without text.

Import Markdown newsfeed

Replace the news field in .ohwr.yaml with the newsfeed field.
The newsfeed field accepts a URL to a markdown file to parse the news from.

Replace "Join" with "Submit project"

Implement search functionality

Add a search form that queries all the projects and takes into consideration labels and categories.

Increase text color contrast

Implement project database file and use it in CI to build our website.

We need a simple text file that will act as a "database" of projects that are part of OHWR.

In the simplest form, this could be one git repo per line. We could also think of making it a bit more complex, in order to add more info that perhaps does not fit in the YAML project info file that we expect to find at the project repo (if such type of info exists).

Once this file is in our repo, we use it in CI to build the project info pages of our website.

Fix project page layout

• Fix margins in project pages
• Truncate license badges for mobile screens
• Open external links in a new tab

Update 'About' page

Currently the 'About' page is filled with placeholder content and needs to be updated.

Modifications should take into consideration that both the first sentence and the image of the 'About' page are being automatically displayed in the 'About OHWR' section of the 'Home' page.

Reduce the size of the category cards

Each category is represented by a card in the 'Categories' section.
To support a large number of categories the category cards should have less white space and be smaller.

Redesign project page

• Links, description and licenses inside a shadowed box
• link icons:
  • increase their size
  • remove their description
  • add a label when hovering with the mouse
  • align them to the right except for the "project website" button
  • reorder - release, documentation, repository, issue tracker, forum
  • replace release icon with fa-rocket
  • replace forum icon with fa-comments
• Licenses:
  • remove badge
  • scale icon with primary color
• Latest news header should be centered

Add Markdown linter

https://github.com/DavidAnson/markdownlint

Update 'Home' page

Currently the Home page is filled with placeholder content and needs to be updated.

The Home page has the following content:

• The logo - is the current logo the final logo? Are the size and position OK?
• The welcome message - needs to be updated.
• A short description of what OHWR is about - needs to be updated.
• A 'Submit Project' button - is this the main button we want to display on the Home page? Is the position OK?
• A summary of the About page - does it look alright? What about the 'Read More' button? And the image? Are the sizes and position OK?
• A carousel with of the featured projects - does it look alright? Are the size and position OK? What about the 'Read More' button?
• The latest news - does it look alright? Are 3 latest news enough? Is the disposition good? Are the sizes and the position OK? Are the 'Read More' buttons OK? Does the label of the project they belong to look alright? What about the position and format of the date? Is the 'See All News' button OK?

Add more static content to the Home page if there's anything missing.

Turn project images into clickable links to the projects

Improve gallery and taxonomies

1. On the project page, the gallery is resizing depending on image, it should have constant size and resize the image instead.
2. On the categories / tabs, the images are cut, scale them down and show smaller but full images.