This repo centralizes the list of projects following the NumPEx Software Integration guidelines.

Human-readable version of the SW catalog is available on this website.

1. Fork this repo and create a new branch
2. Perform a self assesment of your software module with respect to the NumPEx Software Guidelines
3. Record the result into a markdown file, named after the name of your software module (e.g. my_module_name.md) and add this file in the self-assessment folder of your fork
4. Update main-list/projets.json in your fork, by adding an entry for each package you want to include in the NumPEx SW Catalog:

  {
    "name": "My Super Software",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim\nveniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea\ncommodo consequat. Duis aute irure dolor in reprehenderit in voluptate\nvelit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat\ncupidatat non proident, sunt in culpa qui officia deserunt mollit anim id\nest laborum.\n",
    "discussion": "https://example.com/discussion",
    "documentation": "https://example.com/",
    "guix_package": "https://example.com/guix",
    "spack_package": "https://example.com/spack"
  }

5. Initiate a pull request for your changes
6. After screening and evaluation by NumPEx team, your software will be added into the catalog.

In case you have already a Codemeta file in your project repo, we offer an easy solution to avoid any duplication or redundant typing, and to enable automatic updates.

The prerequisite is that you ensure your Codemeta file adheres to the NumPEx conventions for Codemeta. Once this is done, you can proceed with the submission workflow documented above, with the only exception of step 4, which should be replaced by:

4. Update main-list/mapping.json in your fork, by adding an entry in the projects property for each project you want to include :

        {
            "source": "https://url.to.your.repo/codemeta.json",
            "mappingRef": "https://numpex.github.io/sw-catalog/mappings/codemeta-v2-v3.json",
            "allow": "create"
        }

This specifies the location of the Codemeta file for your project, indicates that the standard NumPEx<>Codemeta mapping rules should be applied and that only the "creation" of a new project in the catalog is allowed : this means if someone else already registered a project with the same name in the NumPEx catalog, the script will not just update the existing entry with your new metadata (which would cause a big mess), but trigger an error instead.

After the submission is accepted, the CI system will daily fetch your codemeta file and automatically update the SW Catalog according to the latest content.

The website generates a human-readable of the SW catalog by dynamically parsing the latest commit for the main-list/projects-generated.json file in the main branch. Please be aware that unexpected content in this file may cause erroneous rendering or even undefined behaviour (e.g. webbrowser crash) when users access the catalog page from the website. Make sure to fix any problem in that file asap.

As it name suggests, the projects-generated.json file is generated by the CI system, by applying all the updates specified in main-list/mapping.json to the (human-edited) file main-list/projects.json.

Following workflows are implemented:

• In a pull request: validate the format of projects.json, try to regenerate the projects-generated.json and validate the format of projects-generated.json
• When pushing to main: same + commit the new version of projects-generated.json
• Periodically: same + commit the latest update of projects-generated.json in a new branch & issue a PR (if needed)

More information on the import process and the mapping.json file can be found here.

During the implementation of the automatic import & update process, we identified the need to make certain data available via an HTTP server: the definition of the JSON terms introduced by the NumPEx Codemeta convention, the standard mapping files that available for reference in mapping.json , ... We therefore set up Github pages, with docs/ folder as the publishing source. For instance the file stored under docs/terms-1.0/index.jsonld will be served under the https://numpex.github.io/sw-catalog/terms-1.0/index.jsonld URL. Standard CI workflow is used for the deployment of the Github pages.

Currently the conditions are very loose; we only check:

1. that the self-assesment file is provided
2. that there is no obvious typo in the description or project name
3. that the format of the file is valid (done by CI workflow)

The final HTML page, is generated from 2 repositories:

• This sw-catalog repo, that holds the metadata.
• The tutorials repo, that renders the catalog.

To add a new element for all projects:

1. Add a new property to the schema: https://github.com/numpex/sw-catalog/blob/main/main-list/projects-schema.json
2. Fill the property for all projects: https://github.com/numpex/sw-catalog/blob/main/main-list/projects.json
3. Configure the tutorials page to render the new property:
   1. Modify projects.mjs: https://gitlab.inria.fr/numpex-pc5/tutorials/-/blob/main/docs/assets/js/projects.mjs
   2. Add the new field to the typedef Project (to have the type system properly detect it).
   3. Add a new dispatch function to render a new <li>, similar to the existing ones.
   4. (Optionally) Change the icon from class="fas fa-<name>", from the list of icons of FontAwesome: https://fontawesome.com/icons/packs/classic

The projects are rendered with the following steps:

1. Hugo renders the main page: https://gitlab.inria.fr/numpex-pc5/tutorials/-/blob/main/docs/content/projects/_index.md
2. The {{< projects >}} shortcode calls the following HTML snippet: https://gitlab.inria.fr/numpex-pc5/tutorials/-/blob/main/docs/layouts/shortcodes/projects.html
3. The projects shotcode loads and calls the following Javascript projects.mjs: https://gitlab.inria.fr/numpex-pc5/tutorials/-/blob/main/docs/assets/js/projects.mjs

.
|
├── main-list
│   ├── projects-schema.json           => JSON SCHEMA
│   ├── mapping-schema.json            => JSON SCHEMA
│   ├── projects-generated.json        => THE GENERATED CATALOG - DON'T TOUCH
│   ├── mappings.json                  => INSTRUCTIONS FOR FETCHING FROM EXTERNAL JSON FILES - HUMAN EDITABLE
│   └── projects.json                  => THE LIST OF PROJECTS - HUMAN EDITABLE
|
├── self-assessment                    => THE FOLDER CENTRALIZING SELF-ASSESSMENTS
│   ├── some-sw-module.md
│   └── another_module.md
|
├── scripts                            => THE FOLDER FOR SCRIPTS
|
├── documentation                      => THE FOLDER FOR DOCUMENTATION
|
├── docs                               => THE FOLDER FOR GITHUB PAGES DEPLOYMENT
|
├── .github
│   └── workflows                      => CI WORKFLOWS
|
├── README.md