Incorporated today's feedback

.github/workflows/main.yml

@@ -1,38 +1,61 @@
-name: Deploy to Github Pages
+name: Deploy Next.js site to Pages
 
 on:
  push:
- branches:
- - main
-# on: [push]
+ branches: ["main"]
+
+ workflow_dispatch:
+
 permissions:
- contents: write
+ contents: read
+ pages: write
+ id-token: write
 
 jobs:
- deployment:
-  runs-on: ubuntu-latest
-
+ # Build job
+ build:
+ runs-on: ubuntu-22.04
  steps:
  - name: Checkout
  uses: actions/checkout@v3
  - name: Setup Node
  uses: actions/setup-node@v3
  with:
- node-version: "lts/*"
- cache: "npm"
- - name: Install Node Modules
+ node-version: "18.16.0"
+ cache: npm
+ - name: Restore cache
+ uses: actions/cache@v3
+ with:
+ path: |
+ .next/cache
+ # Generate a new cache whenever packages or source files change.
+ key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
+ # If source files changed but packages didn't, rebuild from a prior cache.
+ restore-keys: |
+ ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
+ - name: Install dependencies
  run: npm ci
- - name: Jest
+ - name: Run Jest Unittests
  run: npm run test:ci
- - name: Cypress run
+ - name: Run Cypress e2e tests
  run: npm run e2e:headless
- - name: Build
- run: |
- npm run build
- npm run export
- - name: Deploy
- # https://github.com/JamesIves/github-pages-deploy-action
- uses: JamesIves/github-pages-deploy-action@v4
+ - name: Build with Next.js
+ run: npm run build
+ - name: Static HTML export with Next.js
+ run: npm run export
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v1
  with:
- branch: gh-pages
- folder: out
+ path: ./out
+
+ # Deployment job
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v2

.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Run tests on merge
+
+on:
+ pull_request:
+ branches: ["main"]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pull-requests: write
+
+jobs:
+ test:
+ runs-on: ubuntu-22.04
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ - name: Setup Node
+ uses: actions/setup-node@v3
+ with:
+ node-version: "18.16.0"
+ cache: npm
+ - name: Install dependencies
+ run: npm ci
+ - name: Run Jest Unittests
+ run: npm run test:ci
+ - name: Run Cypress e2e tests
+ run: npm run e2e:headless
+

BUILDING.md

@@ -9,8 +9,14 @@ This document describes how to build and deploy the gem5 Resources website. It i
 - [Automatic Deployment](#automatic-deployment)
  - [Using GitHub Pages](#using-github-pages)
  - [GitHub Action to Deploy to Github Pages](#github-action-to-deploy-to-github-pages)
- - [Workflow Configuration](#workflow-configuration)
- - [Job: deployment](#job-deployment)
+ - [Workflow Triggers](#workflow-triggers)
+ - [Permissions](#permissions)
+ - [Jobs](#jobs)
+ - [Build Job](#build-job)
+ - [Steps](#steps)
+ - [Deployment Job](#deployment-job)
+ - [Steps](#steps-1)
+ - [Note](#note)
 
 # Running it Locally
 
@@ -63,30 +69,56 @@ serve out
 
 ## Using GitHub Pages
 
-Go to the "Pages" section of GitHub Settings. If deploying to a custom domain, add that information here.
+Go to the "Pages" section of GitHub Settings. If deploying to a custom domain, add that information here. 
+
+In order to host the website on a different domain, firstly you need to add a CNAME file to the `public` directory with the domain name as the content of the file. For example, if you want to host the website on `https://resources.gem5.org`, you need to add a file named `CNAME` to the `public` directory with the content `resources.gem5.org`.
+Next, in order to load the static assets correctly, you need to change the `assetPrefix` and `basePath` properties in the `next.config.js` file. For example, if you want to host the website on `https://resources.gem5.org`, you need to change the `assetPrefix` and `basePath` properties to `undefined` and `/` respectively. If you want to host the website on `https://resources.gem5.org/gem5-resources`, you need to change the `assetPrefix` and `basePath` properties to `/gem5-resources/` and `/gem5-resources` respectively.
 
 ## GitHub Action to Deploy to Github Pages
 
-Our GitHub Actions workflow in `.github/workflows/main.yml` automatically deploys a static website to GitHub Pages when changes are pushed to the "main" branch. It utilizes the [JamesIves/github-pages-deploy-action](https://github.com/marketplace/actions/deploy-to-github-pages) action to perform the deployment
+Our GitHub Actions workflow in `.github/workflows/main.yml` automatically deploys a static website to GitHub Pages when changes are pushed to the "main" branch. It includes a build job to build the Next.js project and run tests, and a deployment job to deploy the built project to GitHub Pages.
+
+### Workflow Triggers
+
+The workflow is triggered in the following cases:
+
+- **Push**: The workflow will be triggered when a push occurs on the `main` branch.
+- **Manual Dispatch**: The workflow can also be manually triggered using the workflow dispatch event.
+
+### Permissions
+
+The workflow requires the following permissions:
+
+- **Contents**: Read access to repository contents.
+- **Pages**: Write access to GitHub Pages.
+- **ID Token**: Write access to GitHub ID token.
+
+### Jobs
+
+#### Build Job
+
+The build job is responsible for building the Next.js project, running tests, and generating static HTML files for export.
 
-### Workflow Configuration
+#### Steps
 
-The workflow is triggered on the push event, specifically for the main branch, and also allows for manual triggering using the workflow_dispatch event.
+1. **Checkout**: Checks out the repository code using the `actions/checkout@v3` action.
+2. **Setup Node**: Sets up the Node.js environment using the `actions/setup-node@v3` action. It specifies the Node.js version (`18.16.0`) and caches the `npm` directory.
+3. **Restore Cache**: Restores the cache to speed up subsequent builds. It caches the `.next/cache` directory and generates a new cache whenever packages or source files change.
+4. **Install Dependencies**: Installs the project dependencies using `npm ci`.
+5. **Run Jest Unittests**: Executes the unit tests using `npm run test:ci`.
+6. **Run Cypress e2e Tests**: Runs the end-to-end tests using `npm run e2e:headless`.
+7. **Build with Next.js**: Builds the Next.js project using `npm run build`.
+8. **Static HTML Export with Next.js**: Generates static HTML files for export using `npm run export`.
+9. **Upload Artifact**: Uploads the built project to be used in the deployment job. It uses the `actions/upload-pages-artifact@v1` action to upload the `./out` directory.
 
-### Job: deployment
+#### Deployment Job
 
-The `deployment` job runs on the `ubuntu-latest` operating system.
+The deployment job is responsible for deploying the built Next.js project to GitHub Pages.
 
-**Steps**:
+#### Steps
 
-1. `Checkout`: This step uses the `actions/checkout` action to checkout the code from the repository.
-2. `Setup Node`: This step uses the `actions/setup-node` action to set up Node.js with the specified LTS (Long-Term Support) version and npm cache.
-3. `Install Node Modules`: This step installs the node modules used in this codebase through `npm ci`.
-4. `Jest`: This step uses Jest.js to run unit test suites on the codebase.
-5. `Cypress run`: This step runs the End-to-End test suite on Cypress.
-6. `Build`: This step performs the following actions:
+1. **Deploy to GitHub Pages**: Deploys the project to GitHub Pages using the `actions/deploy-pages@v2` action. It deploys to the `github-pages` environment and sets the deployment URL based on the output of the previous build job.
 
- - Runs the build script using `npm run build`.
- - Exports the build using `npm run export`.
+#### Note
 
-7. `Deploy`: This step uses the `JamesIves/github-pages-deploy-action` action to deploy the built website to GitHub Pages. It specifies the `./out` directory as the publish directory, which is the directory where the built website is exported. The website is exported to the `gh-pages` branch.
+Make sure to configure your repository's settings to enable GitHub Pages and choose the branch and folder to serve as the source for the deployed site.

MAINTAINING.md

@@ -8,10 +8,13 @@ This document describes how to maintain the gem5 Resources website.
 - [Database Configuration](#database-configuration)
  - [`schemaUrl`](#schemaurl)
  - [`resources`](#resources)
+- [Hosting on a Different Domain](#hosting-on-a-different-domain)
 - [Adding a New Category](#adding-a-new-category)
 - [Adding a New Page](#adding-a-new-page)
 - [Configuring the Tabs](#configuring-the-tabs)
 - [Editing Information on the Help page or About page](#editing-information-on-the-help-page-or-about-page)
+- [Changing CSS](#changing-css)
+- [Adding a JSON file as a Static Page](#adding-a-json-file-as-a-static-page)
 - [Testing Configurations](#testing-configurations)
  - [jest.config.js](#jestconfigjs)
  - [Configuration Details](#configuration-details)
@@ -47,6 +50,11 @@ In case of a **JSON** database, every object must contain the following properti
 - `url`: The Raw GitHub URL of the JSON data, or the local path, with root directory being the `public` directory of this codebase.
 - `isMongo`: A boolean value indicating whether the data source is MongoDB or not, set to false.
 
+# Hosting on a Different Domain
+
+In order to host the website on a different domain, firstly you need to add a CNAME file to the `public` directory with the domain name as the content of the file. For example, if you want to host the website on `https://resources.gem5.org`, you need to add a file named `CNAME` to the `public` directory with the content `resources.gem5.org`.
+Next, in order to load the static assets correctly, you need to change the `assetPrefix` and `basePath` properties in the `next.config.js` file. For example, if you want to host the website on `https://resources.gem5.org`, you need to change the `assetPrefix` and `basePath` properties to `undefined` and `/` respectively. If you want to host the website on `https://resources.gem5.org/gem5-resources`, you need to change the `assetPrefix` and `basePath` properties to `/gem5-resources/` and `/gem5-resources` respectively.
+
 # Adding a New Category
 
 1. If you want to add a new category, make sure it is added as a definition to the gem5 Resources Schema.
@@ -136,8 +144,24 @@ If the configuration for a particular category is not specified, by default, the
 
 To edit the information shown on the Help page or the About page, navigate to `pages/`. Edit the corresponding .md file, `help.md` for the Help page and `about.md` for the About page. Redeploy the website.
 
+# Changing CSS
+
+To edit the CSS of a particular component, navigate to the source code of the compenent, located in the `components/` directory. Find the class name of the CSS you want to edit. You can either change the CSS in the source file itself or navigate to `styles/` and change it there, under `globals.css`.
+
+# Adding a JSON file as a Static Page
+
+Upload the JSON file under `public/`. It should then be viewable at `https://resources.gem5.org/[YOUR_FILE_NAME]`.
+
 # Testing Configurations
 
+All of the tests are run before deployment as well as before merging a pull request. The `tests.yml` file in the `.github/workflows/` directory contains the configuration for running the tests. These are the steps that are run:
+
+1. Checkout the repository
+2. Install Node.js `v18.16.0`
+3. Install dependencies
+4. Run the jest unit tests
+5. Run the Cypress integration tests
+
 ## jest.config.js
 
 This repository contains the configuration file `jest.config.js` for running tests with Jest. The configuration file specifies various settings and options for Jest to customize the testing environment.

README.md

@@ -51,19 +51,22 @@ This is the source code for the gem5 Resources website. It is built using [Next.
 
 The project is structured as follows:
 
-- `gem5.config.js`: Contains the configuration for the gem5 Resources website including the databases and the tabs.
+- `gem5.config.js`: Contains the configuration for the gem5 Resources website including the databases and the tabs. This is config that you would use to make changes to the JSON or MongoDB source information and the location of rendering of resource information for a particular category.
 - `components`: Contains React components used throughout the website.
  - `components/tabs`: Contains the tabs used in the Resource page.
 - `pages`: Contains the pages of the website. Each page is a React component.
  - `pages/api`: Contains the API routes of the website.
  - `pages/category`: Contains the .md documentation of what every category under gem5 Resources is.
-- `public`: Contains static assets such as images, fonts, and favicons.
+- `public`: Contains static assets such as images, fonts, and favicons. Also contains the gem5 Resources Schema and other JSON files of previous versions of gem5.
 - `styles`: Contains global stylesheets and CSS modules.
 - `__tests__`: Contains the jest unit tests for the website.
 - `__mocks__`: Contains the jest mocks for the website.
 - `cypress`: Contains the cypress integration tests for the website.
-- `next.config.js`: Contains the configuration for the Next.js server.
+- `next.config.js`: Contains the configuration for the Next.js server. Includes information on build directories, environment variables and the domain of the website.
 - `docs`: Contains the documentation files for the website.
+- `jest.config.js`: Contains the setup configuration for Jest.js, a unit test framework for JavaScript.
+- `jest.setup.js`: Additional setup for mocking libraries like react-markdown in Jest.js.
+- `cypress.config.js`: Contains the setup configuration for Cypress, an E2E test framework for JavaScript. Tests how various components of the website interact with each other.
 
 
 ## Maintaining the Website

components/tabs/changelogTab.js

@@ -31,7 +31,8 @@ export default function ChangelogTab({ github_url }) {
  const text = await res.text();
  setReadme(text);
  }
- if (!github_url) return;
+ if (!github_url)
+ return setReadme("No GitHub Source for this resource");
  if (!github_url.match(/github\.com\/[a-zA-Z0-9-_.]+\/[a-zA-Z0-9-_.]+/))
  return setReadme("Invalid GitHub URL");
  getReadme();

next.config.js

@@ -1,8 +1,18 @@
 // This file is used to configure Next.js
 const config = require('./gem5.config.json');
 
-assetPrefix = undefined;
-basePath = '';
+basePath = "";
+if (basePath === "") {
+ assetPrefix = ""
+} else {
+ assetPrefix = basePath + '/'
+}
+
+let isProd = process.env.NODE_ENV === 'production'
+if (!isProd) {
+ basePath = ""
+ assetPrefix = ""
+}
 
 module.exports = {
  assetPrefix: assetPrefix,