diff --git a/about/contributing.md b/about/contributing.md index cf8faeb83..cfd014eb5 100644 --- a/about/contributing.md +++ b/about/contributing.md @@ -170,6 +170,20 @@ The informational pages on this site (e.g., this page, [About](/about), [FAQ](/a **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. +Here is a template for creating a new accordion. Somewhat unintuitively, the title of the accordion appears *below* its contents. + +```liquid +{% raw %} +{% capture accordionContent %} + +Text/content goes here + +{% endcapture %} + {% assign accordionContent = accordionContent | markdownify %} + {% include components/accordion.html title='Title of the FAQ in the form of a question?' slug='unique-hash' content=accordionContent %} +{% endraw %} +``` + {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} {% include components/accordion.html title='How do I update the FAQ or other text?' slug='faq' content=accordionContent %} diff --git a/about/faq.md b/about/faq.md index c415802aa..ea5b12827 100644 --- a/about/faq.md +++ b/about/faq.md @@ -35,7 +35,7 @@ If you’re new to GitHub and open source in general, figuring out how to get se * **Company**: `Lawrence Livermore National Laboratory, @LLNL`. * **Location**: Your primary location. {:.mb-3} -3. Add your `@LLNL` email address (and any aliases) to your [Email Settings](https://github.com/settings/emails) page. This will link any commits done via [your Git identity](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#Your-Identity) to your GitHub account. +3. Add your `@llnl.gov` email address (and any aliases) to your [Email Settings](https://github.com/settings/emails) page. This will link any commits done via [your Git identity](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#Your-Identity) to your GitHub account. 4. [Enable two-factor authentication (2FA)](https://github.com/settings/security). * [Learn how to set up 2FA at the Lab ](https://dev.llnl.gov/security-access/2fa). @@ -101,7 +101,7 @@ If you are an employee at LLNL and have 2FA enabled, you are eligible to join th {% 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–even if you plan on setting the repository to *Private* instead of *Public*. 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/). LLNL employees can follow ["one-stop shop" instructions ](https://dev.llnl.gov/open-source/one-stop-shop/) for releasing software. +Before content is placed into an LLNL GitHub.com repository, it should be reviewed and released via LLNL's Information Management (IM) process–even if you plan on setting the repository to *Private* instead of *Public*. All information produced by LLNL must follow the guidance set forth by the LLNL IM/RR policy for both [initial release and incremental contributions ](https://dev.llnl.gov/opensource/contributing/). LLNL employees can follow ["one-stop shop" instructions ](https://dev.llnl.gov/open-source/one-stop-shop/) for releasing software. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} {% include components/accordion.html title='How do I get my repo reviewed and released for GitHub?' slug='released' content=accordionContent %} @@ -117,7 +117,7 @@ Remember that these repositories *are hosted on GitHub* servers, ***not** LLNL s * No controlled unclassified information (CUI) * No unclassified controlled nuclear information (UCNI) -When in doubt, contact a Derivative Classifier (DC) and/or IM for further guidance. +When in doubt, contact a Derivative Classifier (DC) and/or IM/RR for further guidance. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} {% include components/accordion.html title="What is/isn't allowed in my repo?" slug='allowed' content=accordionContent %} @@ -144,12 +144,30 @@ The [JOSS RtD site](https://joss.readthedocs.io/en/latest/submitting.html) descr {% assign accordionContent = accordionContent | markdownify %} {% include components/accordion.html title="My project is approved for release. Now what? What about docs?" slug='approved' content=accordionContent %} +{% capture accordionContent %} + +Most LLNL repos use the standard GitHub URL of `github.com/llnl/*`. However, you may use the `software.llnl.gov` domain, where you append `/*` to it. Alternatively, you can use GitHub pages to create a custom `*.llnl.gov` URL that redirects to `software.llnl.gov/*`. + +| --- | ----- | ---- | +| URL | Setup | Help | +| --- | ----- | ---- | +| `github.com/llnl/*` | [Creating a GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) | | +| `software.llnl.gov/*` | [Configuring a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site) | | +| `*.llnl.gov` | [Managing a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) | | +{:.table .table-striped .table-bordered} + +**Note:** `software.llnl.gov` uses a reverse proxy and is hosted on LLNL Computing servers, which fetches the content from GitHub behind the scenes. If you would like to use the `software.llnl.gov/*` URL, you do *not* need to check the "Enforce HTTPS" box in your repo's settings (Settings > Pages > Custom Domain > Enforce HTTPS). This checkbox is for sites that point directly to GitHub, not the LLNL Computing servers. The team manages the DNS and SSL certificate for `software.llnl.gov` only, not for `*.llnl.gov`. + +{% endcapture %} + {% assign accordionContent = accordionContent | markdownify %} + {% include components/accordion.html title='Can I create a custom URL for my repo?' slug='repo-url' content=accordionContent %} + {% capture accordionContent %} {% capture alertContent %} * 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?](https://software.llnl.gov/about/faq/#released)) and display the appropriate open source license and `LLNL-CODE-xxxxxx` release number. +* All LLNL repos must go through the IM/RR process (see the FAQ [How do I get my repo reviewed and released for GitHub?](https://software.llnl.gov/about/faq/#released)) and display the appropriate open source license and `LLNL-CODE-xxxxxxx` 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 %} @@ -184,7 +202,7 @@ Now that your project is on GitHub, make sure users and contributors can find it * See helpful hints on [GitHub's topic help page](https://help.github.com/articles/about-topics/). Add tags relevant to your project's programming language, platforms, and more (e.g., Python, HPC, Linux). -2. Let [X/Twitter](https://twitter.com/LLNL_OpenSource) followers know your project is available on GitHub. Feel free to tag the `@LLNL_OpenSource` handle on your own tweet, or submit a request to [open-source@llnl.gov](mailto:open-source@llnl.gov) so we can post on your behalf. +2. Let [X/Twitter](https://twitter.com/Livermore_Comp) followers know your project is available on GitHub. Feel free to tag the `@Livermore_Comp` handle in your own post, or submit a request to to post on your behalf. 3. Publicize any outreach activities or major milestones related to your project such as: * A paper/poster/presentation is accepted at a conference @@ -193,7 +211,7 @@ Now that your project is on GitHub, make sure users and contributors can find it * You're guest blogging or speaking on a podcast {:.mb-3} -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. +4. Include a summary of your project with GitHub and documentation links on LLNL's [Computing website](https://computing.llnl.gov/projects). Contact for this particular task. {% endcapture %} {% assign accordionContent = accordionContent | markdownify %} {% include components/accordion.html title='How do I let people know about my new repo?' slug='publicize' content=accordionContent %} @@ -228,13 +246,13 @@ If you need help re-assigning permissions in your repo, contact [github-admin@ll {% 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. +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. Migrating the repo outside of the LLNL organization requires an organization admin. Contact [github-admin@llnl.gov](mailto:github-admin@llnl.gov) to coordinate the move. **Once the repository has moved to the new organization:** -1. Submit a pull request updating the [`input_lists.json` file](https://github.com/LLNL/llnl.github.io/blob/main/_visualize/input_lists.json) to add the new organization/repo's name. This allows for the software catalog to continue including the project even after it moves. +1. Submit a pull request updating the [`input_lists.json` file](https://github.com/LLNL/llnl.github.io/blob/main/_visualize/input_lists.json) to add the new organization/repo's name. This allows the software catalog to continue including the project even after it moves. 2. Retain topic tags (e.g., `math-physics`) to connect it to this website's browsable categories. {% endcapture %} @@ -245,7 +263,7 @@ Migrating the repo outside of the LLNL organization requires an organization adm {% capture alertContent %} -Even if your collection of repos are housed under another organization but developed on behalf of LLNL, they must go through the IM process (see the FAQ [How do I get my repo reviewed and released for GitHub?](https://software.llnl.gov/about/faq/#released)) and display the appropriate open source license and `LLNL-CODE-xxxxxx` release number. +Even if your collection of repos are housed under another organization but developed on behalf of LLNL, they must go through the IM/RR process (see the FAQ [How do I get my repo reviewed and released for GitHub?](https://software.llnl.gov/about/faq/#released)) and display the appropriate open source license and `LLNL-CODE-xxxxxxx` release number. {% endcapture %} {% assign alertContent = alertContent | markdownify %} diff --git a/about/policies/index.md b/about/policies/index.md index ac5db2efb..d3e493809 100644 --- a/about/policies/index.md +++ b/about/policies/index.md @@ -118,6 +118,6 @@ badge](https://img.shields.io/badge/R.lic-3-yellow.svg)](/project/policies/licen ### References [^bss]: [Better Scientific Software](https://bssw.io) -[^xsdk]: [xSDK Community Policies](https://xsdk.info/policies) +[^xsdk]: [xSDK Community Policies](https://github.com/xsdk-project/xsdk-community-policies) [^sl]: [Smart Libraries: Best SQE Practices for Libraries with Emphasis on Scientific Computing](https://www.osti.gov/biblio/936460) [^wsc]: [Weapons Simulation and Computing (WSC) Software Guidelines](https://lc.llnl.gov/confluence/display/WSCSOFT/WSC+Software+Guidelines)