Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

FAQ & accordion updates #677

Merged
merged 2 commits into from
Apr 29, 2024
Merged

FAQ & accordion updates #677

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cfb83eb
add slugs and IM clarification
hauten Mar 29, 2024
b2d840c
add slugs and slug instructions
hauten Mar 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions about/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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 %}

Expand All @@ -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.
Expand All @@ -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 %}

Expand All @@ -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:
Expand All @@ -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 %}

Expand Down Expand Up @@ -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 %}

</div>
<!-- END: Accordions -->
32 changes: 18 additions & 14 deletions about/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <i class="fa fa-light fa-lock"></i>](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 %}
<!-- START: Warning box -->
Expand Down Expand Up @@ -86,7 +86,7 @@ There are several options for configuring 2FA for your GitHub account:
<!-- END: Buttons -->
{% 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).
Expand All @@ -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 <i class="fa fa-light fa-lock"></i>](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:
Expand All @@ -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:
Expand All @@ -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 %}
<!-- START: Warning Box -->
{% 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 %}
Expand All @@ -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 [[email protected]](mailto:[email protected]) if you need help.
Expand All @@ -187,15 +191,15 @@ 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 [[email protected]](mailto:[email protected]) 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.

Before contributing, please contact [[email protected]](mailto:[email protected]) 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.
Expand All @@ -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 %}

Expand All @@ -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 [[email protected]](mailto:[email protected]) 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.
Expand All @@ -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:
Expand All @@ -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 %}

</div>
<!-- END: Accordions -->