From cfb83eb81f8017500218b9e095fb27f9674148cc Mon Sep 17 00:00:00 2001 From: Holly Auten Date: Fri, 29 Mar 2024 12:44:37 -0500 Subject: [PATCH 1/2] add slugs and IM clarification --- about/faq.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/about/faq.md b/about/faq.md index fb9d7834d..1d8f45d84 100644 --- a/about/faq.md +++ b/about/faq.md @@ -41,7 +41,7 @@ If you’re new to GitHub and open source in general, figuring out how to get se * [Learn how to set up 2FA at the Lab ](https://dev.llnl.gov/security-access/2fa). {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I set up a GitHub account?' content=accordionContent %} + {% include components/accordion.html title='How do I set up a GitHub account?' slug='account' content=accordionContent %} {% capture accordionContent %} @@ -86,7 +86,7 @@ There are several options for configuring 2FA for your GitHub account: {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I set up two-factor authentication (2FA)?' content=accordionContent %} + {% include components/accordion.html title='How do I set up two-factor authentication (2FA)?' slug='2fa' content=accordionContent %} {% capture accordionContent %} If you are an employee at LLNL and have 2FA enabled, you are eligible to join the [LLNL GitHub organization](https://github.com/llnl) and appear in the [member list](https://github.com/orgs/LLNL/people). @@ -98,13 +98,13 @@ If you are an employee at LLNL and have 2FA enabled, you are eligible to join th 3. Head over to the [@LLNL People](https://github.com/orgs/LLNL/people) page and make your membership `Public`. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I join the LLNL organization on GitHub?' content=accordionContent %} + {% include components/accordion.html title='How do I join the LLNL organization on GitHub?' slug='join' content=accordionContent %} {% capture accordionContent %} Before content is placed into an LLNL GitHub.com repository, it should be reviewed and released via LLNL's Information Management (IM) process. All information produced by LLNL must follow the guidance set forth by the LLNL IM policy for both [initial release and incremental contributions ](https://dev.llnl.gov/opensource/contributing/). {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I get my repo reviewed and released for GitHub?' content=accordionContent %} + {% include components/accordion.html title='How do I get my repo reviewed and released for GitHub?' slug='released' content=accordionContent %} {% capture accordionContent %} Remember that these repositories *are hosted on GitHub* servers, ***not** LLNL servers*, and content placed in them should be limited to "email-like" communications. That means: @@ -120,7 +120,7 @@ Remember that these repositories *are hosted on GitHub* servers, ***not** LLNL s When in doubt, contact a Derivative Classifier (DC) and/or IM for further guidance. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title="What is/isn't allowed in my repo?" content=accordionContent %} + {% include components/accordion.html title="What is/isn't allowed in my repo?" slug='allowed' content=accordionContent %} {% capture accordionContent %} Make sure your repo contains [community health files](https://github.com/LLNL/.github/tree/main/community-health), including: @@ -142,12 +142,16 @@ If your repo is research software, consider submitting it to the [*Journal of Op The [JOSS RtD site](https://joss.readthedocs.io/en/latest/submitting.html) describes the submission requirements. JOSS defines *research software* as "software that solves complex modeling problems in a scientific context (physics, mathematics, biology, medicine, social science, neuroscience, engineering); supports the functioning of research instruments or the execution of research experiments; extracts knowledge from large data sets; offers a mathematical library; or similar." (You can also [become a reviewer](https://joss.readthedocs.io/en/latest/editing.html#), if you are so inclined.) {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title="My project is approved for release. Now what? What about docs?" content=accordionContent %} + {% include components/accordion.html title="My project is approved for release. Now what? What about docs?" slug='approved' content=accordionContent %} {% capture accordionContent %} {% capture alertContent %} -Repositories within the LLNL organization are owned and managed by LLNL. Please do not create personal repositories here. + +* Repositories within the LLNL organization are owned and managed by LLNL. Please do not create personal repositories here. +* All LLNL repos must go through the IM process (see the FAQ [How do I get my repo reviewed and released for GitHub?](/about/faq/#how-do-i-get-my-repo-reviewed-and-released-for-github)) and display the appropriate open source license and `LLNL-CODE-xxxxxx` release number. +* If the repo wasn't developed at LLNL, its license needs to be clearly indicated. See the [LLNL Software Licensing](/about/licenses) page for examples. + {% endcapture %} {% assign alertContent = alertContent | markdownify %} {% include components/alert.html type="warning" icon="fa-circle-info" content=alertContent %} @@ -164,7 +168,7 @@ If you've set up your repository within the LLNL organization, you don't need to * If you have a project logo, please follow the [Contributing Guidelines](/about/contribute) (see the question *How do I change how a specific repo appears in the catalog?*) for naming and uploading the file. If your repo is part of a non-LLNL organization that has its own avatar, that image will automatically display next to the repo name in the catalog, unless superseded by a repo-specific logo. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I include my repo in the LLNL organization and/or this website’s catalog?' content=accordionContent %} + {% include components/accordion.html title='How do I include my repo in the LLNL organization and/or this website’s catalog?' slug='catalog' content=accordionContent %} {% capture accordionContent %} Now that your project is on GitHub, make sure users and contributors can find it! There are several ways to do this. Contact [open-source@llnl.gov](mailto:open-source@llnl.gov) if you need help. @@ -187,7 +191,7 @@ Now that your project is on GitHub, make sure users and contributors can find it 4. Include a summary of your project with GitHub and documentation links on LLNL's [Computing website](https://computing.llnl.gov/projects). Contact [webmaster-comp@llnl.gov](mailto:webmaster-comp@llnl.gov) for this particular task. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I let people know about my new repo?' content=accordionContent %} + {% include components/accordion.html title='How do I let people know about my new repo?' slug='publicize' content=accordionContent %} {% capture accordionContent %} Submit a pull request! This website is a GitHub repo just like any other LLNL open source project. News is housed in the [`_posts` directory](https://github.com/LLNL/llnl.github.io/tree/main/_posts), and templates are found in the [LLNL/.github repo](https://github.com/LLNL/.github). See [Contributing Guidelines](../contribute) for more information. @@ -195,7 +199,7 @@ Submit a pull request! This website is a GitHub repo just like any other LLNL op Before contributing, please contact [open-source@llnl.gov](mailto:open-source@llnl.gov) with your idea or if you have questions about whether your proposed content requires the LLNL review and release process. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I contribute news or other content to this website?' content=accordionContent %} + {% include components/accordion.html title='How do I contribute news or other content to this website?' slug='contribute-here' content=accordionContent %} {% capture accordionContent %} Yes, you can give external contributors Write access to your GitHub repo. Anyone with Admin access to your repo can enable this: Settings > Collaborators > Manage access > Add people > enter their username and select. @@ -204,7 +208,7 @@ If you don't already have Admin access to your repo, contact [github-admin@llnl. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='Can non-LLNL developers contribute to my project?' content=accordionContent %} + {% include components/accordion.html title='Can non-LLNL developers/collaborators contribute to my project?' slug='collaborators' content=accordionContent %} {% capture accordionContent %} @@ -217,7 +221,7 @@ If you don't already have Admin access to your repo, contact [github-admin@llnl. 4. Change your repo's status via Settings > Manage Access > Who has access > Manage > Danger Zone > Archive this repository (`settings#danger-zone`). Contact [open-source@llnl.gov](mailto:open-source@llnl.gov) if for some reason GitHub won't let you complete this step. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='What should I do if my repo is no longer actively developed/maintained?' content=accordionContent %} + {% include components/accordion.html title='What should I do if my repo is no longer actively developed/maintained?' slug='remove' content=accordionContent %} {% capture accordionContent %} The process to transfer organizational ownership is straightforward, but generally discouraged. This should really only be done for projects that are starting to build a "bigger than LLNL" community, and the decision should not be made lightly. @@ -233,7 +237,7 @@ Migrating the repo outside of the LLNL organization requires an organization adm 3. Update the org in the RADIUSS [`contributor-ci.yaml` file](https://github.com/LLNL/radiuss/blob/main/contributor-ci.yaml), if applicable. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='My repo has grown. How do I move it out of the LLNL organization?' content=accordionContent %} + {% include components/accordion.html title='My repo has grown. How do I move it out of the LLNL organization?' slug='transfer-out' content=accordionContent %} {% capture accordionContent %} Refer to individual projects for their requirements on accepting contributions. (To contribute to this website, see our [Contributing Guidelines](/about/contribute).) In general, though, we follow the "fork and pull" Git workflow model: @@ -249,7 +253,7 @@ Refer to individual projects for their requirements on accepting contributions. 5. If approved, changes will be merged in by a repository maintainer. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I contribute to an LLNL repo?' content=accordionContent %} + {% include components/accordion.html title='How do I contribute to an LLNL repo?' slug='contribute-repo' content=accordionContent %} From b2d840c14af2d9ad16f01b973a91f3fe06c6500a Mon Sep 17 00:00:00 2001 From: Holly Auten Date: Fri, 29 Mar 2024 12:44:46 -0500 Subject: [PATCH 2/2] add slugs and slug instructions --- about/contributing.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/about/contributing.md b/about/contributing.md index 3e270bc54..ae4d46b70 100644 --- a/about/contributing.md +++ b/about/contributing.md @@ -67,7 +67,7 @@ If a word needs to be ignored, see [instructions](https://github.com/crate-ci/ty {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I build this site locally?' content=accordionContent %} + {% include components/accordion.html title='How do I build this site locally?' slug='local' content=accordionContent %} {% capture accordionContent %} A [JSON file](https://github.com/LLNL/llnl.github.io/blob/main/visualize/github-data/category_info.json) 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](../../news).) 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. @@ -108,7 +108,7 @@ Repos that appear on the [RADIUSS site](https://software.llnl.gov/radiuss/projec {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I update the catalog categories?' content=accordionContent %} + {% include components/accordion.html title='How do I update the catalog categories?' slug='categories' content=accordionContent %} {% capture accordionContent %} @@ -133,7 +133,7 @@ An LLNL repo with its own logo also needs the image file name added to [`repo_lo {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I change how a specific repo appears in the catalog?' content=accordionContent %} + {% include components/accordion.html title='How do I change how a specific repo appears in the catalog?' slug='catalog' content=accordionContent %} {% capture accordionContent %} 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. @@ -156,7 +156,7 @@ Software releases are not included in News. See the separate, and automatically {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I update news content?' content=accordionContent %} + {% include components/accordion.html title='How do I update news content?' slug='news' content=accordionContent %} {% capture accordionContent %} @@ -171,9 +171,11 @@ The informational pages on this site (e.g., this page, [About](/about), [FAQ](/a **To modify the site menu:** Update the menu in the [`header.html`](https://github.com/LLNL/llnl.github.io/blob/main/_includes/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. + {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I update the FAQ or other text?' content=accordionContent %} + {% include components/accordion.html title='How do I update the FAQ or other text?' slug='faq' content=accordionContent %} {% capture accordionContent %} This site's [visualizations](../../visualize) are governed by several scripts and queries. See the following `README` files for details: @@ -184,7 +186,7 @@ This site's [visualizations](../../visualize) are governed by several scripts an {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='How do I modify the visualizations?' content=accordionContent %} + {% include components/accordion.html title='How do I modify the visualizations?' slug='viz' content=accordionContent %} {% capture accordionContent %} @@ -262,7 +264,7 @@ No changes yet, if ever: {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} - {% include components/accordion.html title='For site admins only: notes on future and deprecated features' content=accordionContent %} + {% include components/accordion.html title='For site admins only: notes on future and deprecated features' slug='admins' content=accordionContent %}