LLNL Software Catalog

Contributing Guidelines


Home About Contributing Guidelines

The LLNL Software Catalog website is an open source project. We welcome contributions via pull requests as well as questions, feature requests, or bug reports via issues. Contact our team at open-source@llnl.gov with any questions. Please also refer to our FAQ and Code of Conduct.

To contribute to this website, please create a fork of llnl.github.io. Our CI tests are automatically run against every new PR, and passing all tests is a requirement for merging. In general, please:

Before you begin, make sure you have working installs of Git, Ruby, and Bundler. After you fork the repo, make sure you are in the directory you just created by running cd llnl.github.io Then you can use bundler to install the Ruby dependencies (see the Jekyll installation docs for step-by-step guides to setting this up):

bundle install

Running this will install everything in your Gemfile (including Jekyll).

bundle exec jekyll serve

Finally, open http://localhost:4000 in a web browser.

Note: The RADIUSS website and product catalog “live” on this URL but are managed by a separate repo.

Tips

The gems in your sourcefile get updated frequently. It is a good idea to occasionally run bundle update from within your project’s root directory to make sure the software on your computer is up to date.

Sometimes there can be dependency conflicts if your local version of Ruby is different from this repo or GitHub pages deployment settings. You can find the version number of each of GitHub Page’s current dependency’s here. You can often avoid dependency issues if you use the same versions, including for Ruby.

For example, the default version of Ruby used to deploy GitHub Pages on github.com as of 2021-04-08 was Ruby 2.7.1. If you tried running Ruby version 3.0.0 locally on macOS, you’ll need to do some extra steps to correctly install the dependencies for this repository. You’d need to run bundle add webrick as it is no longer a prepackaged dependency with Ruby in 3.0.0. You may also need to run gem install eventmachine -- --with-openssl-dir=/usr/local/opt/openssl@1.1 as MacOS >10.14 doesn’t use OpenSSL from the same path as is still assumed to be in by eventmachine.

Spellcheck

The GitHub workflow currently includes an action for a Rust tool called crate-ci/typos that will spellcheck all posts and pages. If your CI fails, spelling suggestions will be shown and you can manually update the mistakes, or install typos and have all errors fixed automatically:

typos ./_posts ./README.md ./about/faq.md ./about/contributing.md --write-changes

If a word needs to be ignored, see instructions for adding an entry to the _typos.toml file.

A JSON file contains the info for the software catalog categories displayed on the home page: title, Font Awesome icon, description. If any changes need to be made to these categories, just edit the data in the JSON and the home page will reflect your changes automatically. (These catalog categories/topics are distinct from the tags on News posts.) The list below contains each category’s description to ensure consistency in phrasing and length. Note that in some cases the category is plural, but the corresponding tag is singular.

Note: The All Software category appears at the top of the list by virtue of a blank space before the first letter in the title field (see the JSON file linked above). All other categories appear in alphabetical order.

Category Description Tag(s) FA icon
All Software Browse all LLNL open source projects (no tags required) (image: logomark-software.svg)
AI & Machine Learning Integrate artificial intelligence and machine learning into scientific applications artificial-intelligence, deep-learning, machine-learning, neural-network fa-brain-circuit
App Infrastructure Browse tools for basic functionality common in HPC codes app-infrastructure fa-gear-complex-code
Applications Browse scientific simulation codes and IT management tools application fa-laptop-code
Build Tools Automate and simplify complex dependencies and deployments build-tools fa-tools
Data Management & Viz Manage visualizations with robust features and configurable analysis data-management, data-viz fa-display-chart-up
Docs & Tutorials Learn more about our software via documentation, examples, and tutorials docs, documentation, tutorial, tutorials fa-file-lines
File Systems Configure data storage and retrieval for more efficient workloads file-system fa-folders
Math & Physics Libraries Optimize solvers, higher order methods, and AMR frameworks math-physics fa-books
Performance & Workflow Manage and scale complex workflows, tracking, and data collection performance, workflows fa-gauge-high
Portable Execution & Memory Mgmt Automate data motion and memory allocation on advanced architectures memory-management, portability fa-briefcase
Proxy Applications Prepare for testing and porting applications proxy-application fa-clone
System Software Manage laptop and desktop computer systems, HPC clusters, and parallel environments system-software fa-floppy-disk

A repository can have up to 20 tags. In general, topic tags raise a repo’s visibility on GitHub and help users find related projects. The following tags, which are not associated with the home page categories above, are recommended for LLNL repos: amr (adaptive mesh refinement), arbitrary-lagrangian-eulerian (ALE), benchmark, biology, checkpoint, chemistry, cmake, compiler, cpp (C++), data-analysis, energy, exascale-computing, finite-elements, fortran, gpu, graph, high-dimensional-data, hpc, java, javascript, library, materials, materials-science, matlab, molecular-dynamics, monte-carlo, mpi, natural-language-processing, openmp, parallel-computing, pde, python, seismology, shell, simulation, solver, templates, testing, uncertainty-quantification.

Repos that appear on the RADIUSS site are listed in that repo’s contributor-ci.yaml file.

To add a new category to the catalog:

  1. Update the list above with the category name (in alphabetical order), description, and tag.
  2. Update category_info.json with category metadata such as Font Awesome icon, descriptive blurb, and corresponding topic(s).
  3. Tag repos with the new topic as appropriate.

To add/change an icon for a category: Go to the category_info.json file and modify the icon property of the given category. To specify a Font Awesome icon, use the fa property listing the full CSS class for the Font Awesome Icon. To specify a file as an icon, use the path property to specify the absolute path to the icon. If the URL to icon is not in this repository, also specify the domain in the path.

To add your repo to the catalog: See the FAQ How do I include my repo in the LLNL organization and/or this website’s catalog?

Project Tags

See the FAQ How do I include my repo in the LLNL organization and/or this website’s catalog? for information about tagging an individual repo. See the topic How do I update or use the catalog categories? above for information about managing the categories.

Project Logos

The home page displays a logo next to each repo when they appear under the topic categories. If a repo has its own logo, that should display. If not, then the LLNL logo displays by default. There are two steps to adding a logo to this website:

1. Upload the image file.

Repo logo files should follow a naming convention and be added to the logos directory. All files must be in .png format.

  • Repository logo: <repo_name>.png
  • Directory: /assets/images/logos/<org name>

2. Call the image file name.

An LLNL repo with its own logo also needs the image file name added to repo_logos.json.

News posts appear in reverse chronological order (i.e., newest first). The list is curated to promote LLNL’s open source endeavors and community engagement. Posts should be tagged with at least one of the following categories, which are not associated with the catalog browse categories (described above) applied to repos.

  • event - announcement or recap of an event/conference
  • multimedia - synopsis of a video or podcast published on another platform (e.g., YouTube)
  • new-repo - announcement of new repo added to LLNL’s software catalog
  • story - synopsis of a relevant news or research-focused article; profile of a developer

Categories should appear alphabetically in each post’s metadata under the title, with no punctuation between multiple categories:

title: "Title of Post"
categories: multimedia story

LLNL’s .github repo contains .md templates for each of these types of posts. For posts that combine multiple tags (e.g., multimedia, event), a combination of templates may be used. File naming conventions are also provided.

Software releases are not included in News. See the separate, and automatically populated, Releases page.

The informational pages on this site (e.g., this page, About, FAQ) are markdown pages that can be updated with a pull request. Please note the following style preferences:

  • H2 headings in title case
  • H3 headings in sentence case
  • News post titles in title case
  • Accordion titles in the form of a sentence-case question

To update the banner on the home page: The existing RADIUSS message is in a container using the button.html include file.

To modify the site menu: Update the menu in the header.html, rather than adding each page to the menu using page attributes.

To create an accordion slug: Accordion titles automatically generate a unique URL hash so the user can go directly to an expanded accordion using a unique URL. As an accordion’s title is often lengthy question text, a shortened slug can be used to shorten the URL hash. For example, this accordion’s title is How do I update the FAQ or other text? but the hash is the much shorter #faq. Add slug='unique-hash' after the title in the accordion’s include syntax. Slugs should be unique to the page they’re on; in other words, a page should not have two accordions with the same slug.

This site’s visualizations are governed by several scripts and queries. See the following README files for details:

Future Materials Science category

Add Materials Science into the catalog browse by adding this code (alphabetically among the other categories) to /visualize/github-data/category_info.json:

    "Materials Science": {
        "title": "Materials Science",
        "hash": "MaterialsScience",
        "icon": {
            "fa": "fa-hexagon",
            "alt": "Materials Science"
        },
        "description": {
            "short": "Software supporting research in materials design, optimization, and innovation",
            "long": ""
        },
        "topics": [
            "materials",
            "materials-science"
        ]
    },

Deprecated RADIUSS features

April 2022: RADIUSS launched at github.com/llnl/radiuss. See tasks in issue 567. If we ever want/need to reinstate RADIUSS browsing, branding, and other features on this site, here’s what to do:

  • Add RADIUSS back into the catalog browse (i.e., to “live” on this website) by adding this code (as lines 154-168) to /visualize/github-data/category_info.json:
        "RADIUSS": {
            "title": "RADIUSS",
            "hash": "RADIUSS",
            "icon": {
                "path": "/assets/images/radiuss.svg",
                "alt": "RADIUSS logo"
            },
            "description": {
                "short": "Rapid Application Development via an Institutional Universal Software Stack",
                "long": ": LLNL's RADIUSS project aims to broaden usage across LLNL and the open source community of a set of libraries and tools used for HPC scientific application development."
            },
                "topics":[
                "radiuss"
            ]            
        },

Note that /project/category_info_radiuss.json is not currently being used. If it were to be reinstated, it would need its categories updated to match the latest Catalog (e.g., Docs and Tutorials`).

  • Comment back in lines 31-38 in Category.service.js
    this.containsRadiussTopics = function(catTopics, repoTopics) {
        for (var i = 0; i < catTopics.length; i++) {
            if ($.inArray(catTopics[i], repoTopics) != -1 && $.inArray('radiuss', repoTopics) != -1) {
                return true;
            }
        }
        return false;
    };

No changes yet, if ever:

  • Policies & Guidelines are currently still on this site: (/about/policies)
  • RADIUSS logo (radiuss.svg) is still in the /assets/ folder
Lawrence Livermore National Laboratory
7000 East Avenue • Livermore, CA 94550 | LLNL-WEB-458451
Operated by the Lawrence Livermore National Security, LLC for the Department of Energy's National Nuclear Security Administration Learn about the Department of Energy's Vulnerability Disclosure Program