Add initial scaffold for content development (#5)

* environment and lint config

* update readme and add initial jupyterbook content

* add dev build task

* add citation file

* minor changes

* add a pull request template

* add contributing

* update dev deps

* update scaffold content

* rename license file with extension

* update tests

* linting

* make the actions reusable

* move the actions

* add actionlint to pre-commit

* add private key prevention check

* move sandbox content to tests

* update contributing

* Apply suggestions from code review

Co-authored-by: Gregory Way <[email protected]>

* add note about how and where to get help

* add issue templates for features and bugs

* linting

* add pre-commit run step to pull request template

* expand node usage explanation

* add contributing link to readme

---------

Co-authored-by: Gregory Way <[email protected]>

.alexignore

@@ -0,0 +1,2 @@
+/src/almanac/_build
+poetry.lock

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,81 @@
+# GitHub Issue template for bug reports
+name: 🐞 Bug
+description: >
+  Help us improve by sharing an error or otherwise broken experience.
+
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thank you for taking time to raise a bug for our awareness!
+
+        If this bug entails a security-focused aspect, please submit a
+        security report instead using GitHub's
+        [report vulnerability form]
+        (https://github.com/software-gardening/almanac/security/advisories/new)
+        .
+
+  - type: checkboxes
+    attributes:
+      label: Existing issue check
+      description: >
+        Please make sure to search in the
+        [issues](https://github.com/software-gardening/almanac/issues) first
+        to see whether the same issue was reported already.
+        If you find an existing issue, please don't hesitate to comment
+        on it or add a reaction to existing content!
+      options:
+        - label: >
+            I found no existing
+            [issues](https://github.com/software-gardening/almanac/issues)
+            covering this topic.
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >
+        Please provide a specific description of what you experienced
+        including links and other references where possible.
+      placeholder: >
+        For example: "I tried `x` and noticed `y` which resulted in `z`."
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Reproducible example
+      description: >
+        How could one reproduce this error or experience?
+        Please provide the steps one must follow to recreate what you observed.
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: >
+        Please provide the version of the Software Gardening Almanac,
+        operating system (OS), etc.
+      placeholder: |
+        - The version of the Software Gardening Almanac you're referencing.
+        - Operating system (e.g. MacOS, Windows, etc.)
+        - Device type (e.g. laptop, phone, etc.)
+    validations:
+      required: true
+
+  - type: checkboxes
+    attributes:
+      label: Would you like to work on a solution for this?
+      description: >
+        The Software Gardening Almanac is a community-driven project and we
+        love new contributors (including through opening new issues)!
+        This is an optional check to help us understand your interest to be
+        involved (especially if you already have a good understanding
+        of how to implement it).
+        We are happy to guide you in the contribution process and please
+        don't hesitate to reach out for help along the way.
+      options:
+        - label: Yes I am willing to submit a PR!

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+# GitHub Issues templates configuration
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,72 @@
+# GitHub Issue template for bug reports
+name: ✨ Feature
+description: >
+  Collaborate with us to enhance this effort with a new feature that
+  doesn't yet exist.
+
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thank you for taking time to share a new feature or capability
+        which doesn't yet exist!
+
+        If this feature entails a security-focused aspect, please submit
+        a security report instead using GitHub's
+        [report vulnerability form]
+        (https://github.com/software-gardening/almanac/security/advisories/new)
+        .
+
+  - type: checkboxes
+    attributes:
+      label: Existing issue check
+      description: >
+        Please make sure to search in the
+        [issues](https://github.com/software-gardening/almanac/issues) first
+        to see whether the same issue was reported already.
+        If you find an existing issue, please don't hesitate to comment
+        on it or add a reaction to existing content!
+      options:
+        - label: >
+            I found no existing
+            [issues](https://github.com/software-gardening/almanac/issues)
+            covering this topic.
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >
+        Please provide a specific description of what you'd like to see
+        including the context and what the result might look like.
+        Consider providing this information in the form of a
+        [user story](https://en.wikipedia.org/wiki/User_story) if possible.
+      placeholder: >
+        For example: "As a <role> I'd like to see <capability>, so that
+        <benefit>."
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Example
+      description: >
+        Are there any examples which could help illustrate or implement
+        the feature?
+    validations:
+      required: true
+
+  - type: checkboxes
+    attributes:
+      label: Would you like to work on a solution for this?
+      description: >
+        The Software Gardening Almanac is a community-driven project and we
+        love new contributors (including through opening new issues)!
+        This is an optional check to help us understand your interest to be
+        involved (especially if you already have a good understanding
+        of how to implement it).
+        We are happy to guide you in the contribution process and please
+        don't hesitate to reach out for help along the way.
+      options:
+        - label: Yes I am willing to submit a PR!

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+<!-- _modified from [EmbeddedArtistry](https://embeddedartistry.com/blog/2017/08/04/a-github-pull-request-template-for-your-projects/)_
+_referenced with modifications from [pycytominer](https://github.com/cytomining/pycytominer/blob/master/.github/PULL_REQUEST_TEMPLATE.md)_ -->
+
+# Description
+
+<!--
+Thank you for your contribution to the Software Gardening Almanac!
+
+Please _succinctly_ summarize your proposed change.
+Namely, consider addressing the following questions:
+
+- What motivated you to open this pull request?
+- Were there any special adjustments you had to make to complete the work?
+- Are there any issues which are related to this pull request (you may used a `#<digit>` to reference GitHub issues as links within this description)?
+
+Also, if you haven't already, please use `pre-commit run --all-files` to help check your files using this project's pre-commit configuration.
+-->
+
+## What is the nature of your change?
+
+- [ ] Content additions or updates (adds or updates content)
+- [ ] Bug fix (fixes an issue).
+- [ ] Enhancement (adds functionality).
+- [ ] Breaking change (these changes would cause existing functionality to not work as expected).
+
+# Checklist
+
+Please ensure that all boxes are checked before indicating that this pull request is ready for review.
+
+- [ ] I have read the [CONTRIBUTING.md](CONTRIBUTING.md) guidelines.
+- [ ] My code follows the style guidelines of this project.
+- [ ] I have performed a self-review of my own contributions.
+- [ ] I have commented my content, particularly in hard-to-understand areas.
+- [ ] I have made corresponding changes to related documentation (outside of book content).
+- [ ] My changes generate no new warnings.
+- [ ] New and existing tests pass locally with my changes.
+- [ ] I have added tests that prove my additions are effective or that my feature works.
+- [ ] I have deleted all non-relevant text in this pull request template.

.github/actions/install-node-env/action.yml

@@ -0,0 +1,14 @@
+# action for installing node and related dependencies
+name: Install node env
+description: |
+  Setup node, and npm for use with GitHub Actions workflows.
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: "21.7"
+    - name: Install npm dependencies
+      shell: bash
+      run: |
+        npm install

.github/actions/install-python-env/action.yml

@@ -0,0 +1,19 @@
+# action for installing python and related dependencies
+name: Install python env
+description: |
+  Setup python, and poetry for use with GitHub Actions workflows.
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    - name: Setup poetry
+      shell: bash
+      run: |
+        python -m pip install poetry
+    - name: Install poetry dependencies
+      shell: bash
+      run: |
+        poetry install

.github/workflows/pre-commit-checks.yml

@@ -0,0 +1,20 @@
+---
+# used for running pre-commit checks
+name: pre-commit checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  pre_commit_checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install python env
+        uses: ./.github/actions/install-python-env
+      - name: Install node env
+        uses: ./.github/actions/install-node-env
+      - uses: pre-commit/[email protected]

.github/workflows/pytest-tests.yml

@@ -0,0 +1,19 @@
+# used for running pytest tests
+name: pytest tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  pytest_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install python env
+        uses: ./.github/actions/install-python-env
+      - name: Run pytest
+        run: |
+          poetry run pytest