diff --git a/.github/codecov.yml b/.github/codecov.yml index 5f645d3..5103007 100644 --- a/.github/codecov.yml +++ b/.github/codecov.yml @@ -6,19 +6,37 @@ coverage: target: auto threshold: 5 base: auto - flags: - - "unit" paths: - "src/" - - "!tests/" + - "tests/" # advanced settings - # branches: - # - main + branches: + - main + - dev if_ci_failed: error #success, failure, error, ignore informational: false only_pulls: false - tests: # declare a new status context "tests" - target: 100% # we always want 100% coverage here - paths: - - "tests/" # only include coverage in "tests/" folder - only_pulls: true + +comment: + layout: "header, diff, components" # show component info in the PR comment + +component_management: + default_rules: + statuses: + - type: project + target: auto + branches: + - "!main" + individual_components: + - component_id: module_python + name: python code + paths: + - src/python/** + - component_id: module_ext + name: C++ code + paths: + - src/ext_modules/** + - component_id: module_tests + name: tests + paths: + - tests/** diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..f40bd49 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,95 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL Advanced" + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: '42 21 * * 3' + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + # Runner size impacts CodeQL analysis time. To learn more, please see: + # - https://gh.io/recommended-hardware-resources-for-running-codeql + # - https://gh.io/supported-runners-and-hardware-resources + # - https://gh.io/using-larger-runners (GitHub.com only) + # Consider using larger runners or machines with greater resources for possible analysis time improvements. + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + permissions: + # required for all workflows + security-events: write + + # required to fetch internal or private CodeQL packs + packages: read + + # only required for workflows in private repositories + actions: read + contents: read + + strategy: + fail-fast: false + matrix: + include: + - language: c-cpp + build-mode: manual + - language: python + build-mode: none + # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift' + # Use `c-cpp` to analyze code written in C, C++ or both + # Use 'java-kotlin' to analyze code written in Java, Kotlin or both + # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both + # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis, + # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning. + # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how + # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + + # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs + # queries: security-extended,security-and-quality + + # If the analyze step fails for one of the languages you are analyzing with + # "We were unable to automatically build your code", modify the matrix above + # to set the build mode to "manual" for that language. Then modify this step + # to build your code. + # ℹ️ Command-line programs to run using the OS shell. + # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun + - if: matrix.build-mode == 'manual' + shell: bash + run: | + echo 'If you are using a "manual" build mode for one or more of the' \ + 'languages you are analyzing, replace this with the commands to build' \ + 'your code, for example:' + echo ' make bootstrap' + echo ' make release' + python -m pip install pybind11 setuptools + python setup.py build_ext + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml new file mode 100644 index 0000000..f022b2b --- /dev/null +++ b/.github/workflows/continuous-integration.yml @@ -0,0 +1,82 @@ +name: Continuous Integration + +on: + push: + branches: + - main + pull_request: + workflow_dispatch: + +defaults: + run: + shell: bash + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + version: ["3.9", "3.10", "3.11", "3.12"] + steps: + + - name: Harden Runner + uses: step-security/harden-runner@17d0e2bd7d51742c71671bd19fa12bdc9d40a3d6 # v2.8.1 + with: + egress-policy: audit + + - name: Check out the commit + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: ~${{ matrix.version }} + + - name: Install development dependencies + run: | + python3 -m pip install --upgrade pip + python3 -m pip install -r requirements.txt + python3 -m pip install tomli + + - name: Test install + run: python3 -m pip install .[tests] + + - name: Test with pytest + run: python3 -m pytest --cov=sansmic --cov=tests examples/ tests/ + + - name: Upload coverage reports to Codecov + uses: codecov/codecov-action@v3 + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + + # - name: Check documentation coverage + # run: | + # make coverage + # mv build/coverage/python.txt ../docs-coverage-report-${{ matrix.version }}.txt + # working-directory: ./docs + + # - name: Archive documentation coverage results + # uses: actions/upload-artifact@v3 + # with: + # name: docs-coverage-report-${{ matrix.version }} + # path: docs-coverage-report-${{ matrix.version }}.txt + + - name: Test uninstall + run: python3 -m pip uninstall -y my-repository-name + + # commits: + # runs-on: ubuntu-latest + # steps: + # - name: Harden Runner + # uses: step-security/harden-runner@17d0e2bd7d51742c71671bd19fa12bdc9d40a3d6 # v2.8.1 + # with: + # egress-policy: audit + + # - name: Conventional Commits + # uses: taskmedia/action-conventional-commits@9148865058f63a6cb560ff4bfd7d534505f43646 # v1.1.3 + # with: + # types: > + # build|chore|ci|docs|feat|fix|minor|patch|perf|style|refactor|test diff --git a/.gitignore b/.gitignore index 7053905..7926763 100644 --- a/.gitignore +++ b/.gitignore @@ -167,3 +167,4 @@ _local/ docs/apidocs/pymodule/** docs/apidocs/clibrary/** +DEPLOY.bat diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d9ff3de --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,470 @@ +# Contributing to sansmic + +Thanks so much for your willingness to help out with sansmic's +development :grinning: Here's everything you need to know. + + + +## Contributor License Agreement + +By contributing to this software project, you are agreeing to the following +terms and conditions for your contributions: + +* You agree your contributions are submitted under the + [BSD 3-Clause License](LICENSE). +* You represent you are authorized to make the contributions and grant the + license. If your employer has rights to intellectual property that includes + your contributions, you represent that you have received permission to make + contributions and grant the required license on behalf of that employer. + + + +## Setting Up Your Environment + +Before you begin hacking on sansmic, you'll need to do a few things: + +1. **Fork the Repository:** On [sansmic's main page][homepage], in + the top-right corner, you'll see a button to [fork the repository][fork]. + Do so, and then clone your fork and set it up with + ```bash + git clone git@github.com:${USER}/sansmic + cd sansmic + git remote add upstream git@github.com:sandialabs/sansmic + git fetch upstream + ``` +2. **Set Up your Environment:** Install the requirements with + ```bash + pip install --user --editable .[dev,docs,test] + ``` +3. **Documentation:** To build the documentation, you will need to also + obtain Doxygen as well as Sphinx. Sphinx will be installed with the + pip command above, but you will need to [install Doxygen][doxygen]. + Afterwards, you can build a local copy of the documentation with + ```bash + cd docs + make html + ``` + +[homepage]: https://github.com/sandialabs/sansmic +[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo +[doxygen]: https://www.doxygen.nl/ + +### Pre-Commit + +We use [pre-commit][precommit] to ensure adherence to good software development +practices, enforce our style guide, etc. To set yourself up with it, ensure +you have your development environment activated, and then run +```bash +cd /path/to/sansmic +pre-commit install +pre-commit install --hook-type commit-msg --hook-type pre-push --hook-type black +``` + +[precommit]: https://pre-commit.com/ + +The checks we perform are the following: +* Ensure no large files are added to the repository. +* Check for files that would conflict in case-sensitive filesystems. +* Ensure files don't contain merge conflict strings. +* Ensure files end with a single blank line. +* Ensure we only use Unix line endings. +* Trim trailing whitespace. +* Use black to format python code. + +### VS Code + +Our IDE of choice is [VS Code][vscode]. Download and install it, and then +follow the instructions below to get it set up. + +[vscode]: https://code.visualstudio.com/ + +#### Getting Started + +For getting up and running with VS Code, check out the following resources: + +* [Visual Studio Code: Introductory Videos][videos] +* [Visual Studio Code: Getting Started][gettingstarted] documentation +* One-page reference of keyboard shortcuts for [Linux][linux], [MacOS][mac], + and [Windows][win] + +[videos]: https://code.visualstudio.com/docs/getstarted/introvideos +[gettingstarted]: https://code.visualstudio.com/docs +[linux]: https://code.visualstudio.com/shortcuts/keyboard-shortcuts-linux.pdf +[mac]: https://code.visualstudio.com/shortcuts/keyboard-shortcuts-macos.pdf +[win]: https://code.visualstudio.com/shortcuts/keyboard-shortcuts-windows.pdf + +#### Extensions + +VS Code is highly customizable through the use of extensions. Click on the +building blocks icon on the left-hand side to open the **EXTENSIONS** panel to +search for and install them. These are the ones we recommend: + +**General** +* **Better Comments:** Style comments in a more human-friendly manner. +* **Code Spell Checker:** Catch spelling mistakes in code and comments. +* **Conventional Commits:** Adhere to the [Conventional Commits][conventional] + specification for commit messages. +* **Coverage Gutters:** Display test coverage in the editor. +* **GitLens — Git supercharged:** Integrate some of the powerful features of + [GitKraken][kraken] into VS Code. +* **IntelliCode:** AI-assisted development features. +* **Pre-Commit:** Commands and helpers for executing pre-commit hooks. +* **Test Explorer UI:** Extensible user interface for running your tests in VS + Code. +* **Vim:** For when you can't truly leave vi behind (and who would want to?). +* **vscode-icons:** Icons for the file explorer. +* INSERT OTHERS +* AS NEEDED + +[conventional]: https://www.conventionalcommits.org/en/v1.0.0/ +[kraken]: https://www.gitkraken.com/ + +**Python-Specific** +* **Python:** The basic extension for Python code in VS Code. +* **Pylance:** Language server for syntax checking your python code. +* **isort:** Sort imports in python code to be consistently ordered and prioritized. +* **Black formatter:** Format python files without needing to wait for pre-commit. +* **Jupyter:** Run and develop the example notebooks. + +**C++-Specific** +* **C/C++:** Basic C/C++ support. +* **C/C++ Extension Pack:** Extra extensions that help with C++ development. + +#### Settings + +After installing the various extensions, you'll also want to customize your +**Settings**. Some things can be set in the [Settings editor][settings]: + +[settings]: https://code.visualstudio.com/docs/getstarted/settings#_settings-editor + +* Text Editor + * Font + * **Font Family:** Add "'Hack FC Ligatured', " to the beginning of the + list. You'll also want to install the [Ligatured Hack fonts][hack] on + your system. + * Files + * **Auto Save:** Set to "onFocusChange". + * **Trim Trailing Whitespace:** Check. +* Extensions + * Conventional Commits + * **Show Editor:** Check. + * **Silent Auto Commit:** Check. + * coverage-gutters + * **Coverage-gutters: Show Line Coverage:** Check. + * **Coverage-gutters: Show Ruler Coverage:** Check. + * Git + * **Allow Force Push:** Check. + * **Autofetch:** Set to "true". + * **Enable Smart Commit:** Check. + * **Fetch On Pull:** Check. + * **Prune On Fetch:** Check. + * **Rebase When Sync:** Check. This makes it such that you use `git pull + --rebase` when pulling. + * **Show Push Success Notification:** Check. + * **Terminal Git Editor:** Check. + * pre-commit-helper + * **Run On Save:** Select "all hooks". + * Vim + * **Vimrc:** Enable: Check. + * Black + * **Black:** Enable: Check. + + +[hack]: https://github.com/gaplo917/Ligatured-Hack + +Other items can be customized in the [`settings.json` file][settingsjson]. +Consider adding the following snippets: + +[settingsjson]: https://code.visualstudio.com/docs/getstarted/settings#_settingsjson + +* To use ligatures to make multi-character symbols in code more readable, add + ```json + "editor.fontLigatures": true + ``` +* To add vertical rulers to the editor window, add + ```json + "editor.rulers": [ + 72, + 79 + ] + ``` +* If you'd like the UI to preserve the scope that you're currently editing at + the top of the file as you scroll through it, you can add + ```json + "editor.experimental.stickyScroll.enabled": true + ``` +* To turn on search highlighting when using the Vim extension, add + ```json + "vim.hlsearch": true + ``` + +## Coding Standards + +Many of our coding standards are applied and enforced using +[pre-commit][precommit] (see [above](#pre-commit)). In addition to what's +handled automatically, we have the following. + +### Documentation + +All code should be appropriately documented using NumPy or Google style +docstrings (NumPy format is preferred) that can be parsed using Sphinx. +You should build the documentation locally to make sure that everything is +working correctly before creating a pull request. + +Any new functionality that is added should also be added to the User Guide. +Documentation that goes into the User Guide must be appropriate, in English, +and free of typos and grammatical errors. If you are unsure about it, we +recommend copying your documentation into a word processor to verify that +it is correct. While we appreciate that spelling is different in different +countries, please use U.S. English spellings to keep documentation consistent +(sorry, but we can't modelling nor generating colour pictures here). + +### Testing + +All new functionality must come with unit tests. Existing tests must be run +and pass prior to a pull request being accepted. Do not change existing tests +without verifying with the maintainers that such action would be appropriate, +since doing so would indicate a major change in the codebase. + +### Best Practices + +Please create an issue, or cite an existing issue when you add code, as this +helps show that the codebase is moving forward with purpose. + + +## Creating Issues + +Create [issues][issues] in GitHub for any work that needs to be done. + +[issues]: https://github.com/sandialabs/sansmic/issues + +### Markdown + +[Markdown][markdown] is a lightweight markup language with plain text +formatting syntax. GitHub uses a form of it for rendering issue and pull +request descriptions and comments, wiki pages, and any files in your +repositories with a `.md` extension (such as this one). For more details on +what's possible with GitHub-flavored Markdown, [see the documentation][gfm]. + +[markdown]: https://en.wikipedia.org/wiki/Markdown +[gfm]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax + +### Issue Templates + +When creating an issue, select one of the available issue templates, and then +follow the instructions that appear in the template. + +### Labels + +The [sansmic > Labels][labels] page shows you all the labels we use, +along with their descriptions. "Type" labels will be applied automatically +when an issue is created via the issue template. "Stage" labels are used to +keep track of what work is being done at any given time. Other labels can be +added as appropriate. + +[labels]: https://github.com/sandialabs/sansmic/labels + + + +## Working Issues + +### Planning Work + +Depending on the needs of the sansmic user base, a project maintainer +will schedule issues to be tackled in the near future by applying the +"Stage: Soon" label. An issue can then be grabbed by a member of the +development team when they have some time available to work on it. + +> **Note:** If you're working on something that hasn't been +> scheduled—e.g., you're tackling a quick bug fix, or are tinkering with +> a feature you'd like to see added—don't worry about the "Stage: Soon" +> label; just work on it as per the rest of the guidelines below. + +### When Work Begins + +First switch the label from "Stage: Soon" to "Stage: Development". Next make +sure your local `master` branch is up-to-date with +```bash +git checkout master +git pull --ff-only upstream master +``` + +> **Note:** You should never be making commits on your `master` branch. The +> `--ff-only` ensures you only update your local `master` branch if it can be +> fast-forwarded. + +Once `master` is updated, you then create a feature branch off of it with +```bash +git checkout -b +``` + +The recommended branch naming convention is to use the issue number, followed +by a hyphen, followed by the issue title, all lowercase, omitting special +characters, and replacing spaces with hyphens. For instance, if issue number +123 has "Implement Awesome New Feature" as the title, the corresponding branch +name would be `123-implement-awesome-new-feature`. + +### As Work Continues + +Do whatever work is necessary to address the issue you're tackling. Break your +work into logical, working commits. Use the **Conventional Commits** extension +for VS Code (or something similar) to ensure your commit messages adhere to the +[Conventional Commits specification][conventional]. + +Feel free to commit and push small chunks early and often and then use +interactive rebase to reorganize your commits before sharing. + +> **Note:** If you rebase a branch that's already been pushed to a remote, +> you'll wind up changing the history, which will require a force push. That +> is permissible (even encouraged), but if you've had one or more reviewers or +> collaborators working with you on the branch, *get their buy-in first* before +> doing a force push. + +### When Work is Complete + +While working on your feature in your local `` branch, other +commits will likely make it into the upstream `master` branch. There are a +variety of ways to merge these changes into your local feature branch. One +possibility is +```bash +git checkout master +git pull --ff-only upstream master +git checkout +git rebase master +``` + +though there are others that are equally valid. Once all is well, create a +pull request (see below). + +### Closing Old Issues + +If at any point you encounter an issue that will not be worked in the +foreseeable future, it is worthwhile to close the issue such that we can +maintain a reasonable backlog of upcoming work. Do be sure to include in the +comments some explanation as to why the issue won't be addressed. + + + +## Pull Requests + +The only way changes get into `master` is through pull requests. When you've +completed work on an issue, push your branch to your fork with `git push -u +origin `, and then create a pull request. Apply the same "Type" +label as the issue, and then return to the issue and swap "Stage: Development" +for "Stage: Review". + +### Reviews + +A project maintainer will review your pull request. Work with them to get your +changes into an acceptable state. + +### Drafts + +You may wish to have your changes reviewed by colleagues before they are ready +to be merged into `master`. To do so, create a [draft pull request][drafts]. +GitHub will not allow you to merge a draft request. When it's ready for +review, you can [mark it as ready][ready]. + +[drafts]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests +[ready]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review + +### Continuous Integration + +GitHub Actions is GitHub's continuous integration and delivery (CI/CD) +mechanism. The configurations for our workflows can be found in the `*.yml` +files in [the `.github/workflows` directory](.github/workflows) in the +repository root: +* INSERT + +In addition to the GitHub Actions workflows, we also integrate with the +following services: +* [Codecov][codecov]: We calculate and publish code coverage details for all + PRs and merged into `master`, and the service comments on PRs indicating any + changes in coverage compared to the base branch. +* [pre-commit.ci][precommitci]: We ensure all the `pre-commit` checks we + encourage developers to run locally also run in CI. +* INSERT OTHERS + +[codecov]: https://about.codecov.io/ +[precommitci]: https://pre-commit.ci/ + +### Merging + +When the review is finished and changes are ready to be merged into `master`: +1. Rebase your feature branch on top of the latest `master`. +2. Clean up your branch with an interactive rebase, squashing down to the + smallest number of commits that makes sense. If there are successive + distinct changes in a pull request, it's fine for those to be preserved in + separate commits. +3. Notify your reviewers that the request is ready to merge. +4. Wait for them to merge the request. +5. Ensure the post-merge CI pipeline also succeeds. + + + +## Conventional Comments + +When commenting on issues and pull requests, we endeavor to adhere to the +[Conventional Comments specification][conventionalcomments] wherever +applicable. Comments should have the form +``` +