Merge branch 'master' into fix-docs

devosoft · Dec 7, 2023 · e0d4cda · e0d4cda
2 parents bdada3c + fc374d2
commit e0d4cda
Show file tree

Hide file tree

Showing 188 changed files with 513 additions and 108 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -97,25 +97,61 @@ jobs:
       - run: export CXX=clang++ && make install-coverage-dependencies
       - run: export CXX=clang++ && make coverage
       - run: curl -s https://codecov.io/bash | bash
+  # adapted from https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#publishing-a-package-using-an-action
+  build-container:
+    name: Build Docker Image
+    runs-on: ubuntu-22.04
+    env:
+      REGISTRY: ghcr.io
+      IMAGE_NAME: ${{ github.repository }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: type=raw,value=ACTIONS_BUILD_${{ github.run_number }}
+      - name: Push to GHCR
+        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
   test-documentation:
     name: Test Documentation Build
     runs-on: ubuntu-22.04
+    needs: build-container
+    container:
+      image: ghcr.io/devosoft/empirical:ACTIONS_BUILD_${{ github.run_number }}
+      # github actions requires root to access mounted volumes
+      options: --user root
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v1
         with:
           submodules: 'recursive'
-      - uses: mmore500/actions-setup-docker@94429ebc8d9edb4e8c8afb2667bce1e89435f74f
-      - run: docker build -t devosoft/empirical .
-      - run: docker ps -a
-      - run: sudo docker run --name empirical devosoft/empirical /bin/bash -c "set -o pipefail && cd /opt/Empirical/doc && make html coverage | ./headtail.sh && python3 /opt/Empirical/doc/parse_documentation_coverage.py /opt/Empirical/doc/_build/doc-coverage.json >> /opt/Empirical/doc-coverage.json"
-      - run: sudo docker cp empirical:/opt/Empirical/doc-coverage.json .
+      - run: |
+          make -C doc html coverage | ./doc/headtail.sh
+          python doc/parse_documentation_coverage.py doc/_build/doc-coverage.json >> doc/doc-coverage.json
       - uses: sylvanld/action-storage@v1
         if: github.ref == 'refs/heads/master'
         with:
           src: doc-coverage.json
           dst: stats/doc-coverage.json
-  deploy-dockerhub:
-    name: Deploy to DockerHub
+  deploy-container:
+    name: Deploy to DockerHub and ghcr.io
     runs-on: ubuntu-22.04
     if: github.ref == 'refs/heads/master'
     needs:
@@ -137,3 +173,12 @@ jobs:
           password: ${{ secrets.DOCKER_PASSWORD }}
           repository: devosoft/empirical
           tag_with_ref: true
+      - name: Push to GHCR
+        uses: docker/build-push-action@v1
+        with:
+          context: .
+          push: true
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          repository: devosoft/empirical
+          tag_with_ref: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,48 @@
+# Contributing to Empirical
+
+We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Proposing new features
+- Submitting new code
+- Writing documentation
+
+## Reporting bugs
+
+To report bugs, please [open an issue on Github](https://github.com/devosoft/Empirical/issues)
+clearly stating the observed (buggy) behavior (screenshots are encouraged), the desired behavior,
+which operating system and compiler you're using (including version), and any additional information that might
+help us fix the bug. If possible, please provide a minimum example that reproduces the bug.
+
+## Requesting features
+
+We welcome suggestions for how to make Empirical better! To give us your ideas, [open an issue on Github](https://github.com/devosoft/Empirical/issues).
+
+## Submitting new code and documentation
+
+Empirical is developed by a group of computational scientists, none of whom can be full-time software developers.
+We try to fix bugs and implement new features as quickly as we can, but we can't make any promises.
+For these reasons, we highly encourage contributors to submit code fixing bugs or implementing new features!
+By working together, we can have a more versatile and robust library than any of us could write individually.
+
+Before writing new code, we reccomend opening an issue or commenting on an existing one to make sure that we're all on the
+same page and agree that your contribution will be consistent with Empirical's goals.
+
+In-depth guides to [getting started with Empirical development](https://empirical.readthedocs.io/en/latest/dev/getting-started.html),
+[coding guidelines for Empirical development](https://empirical.readthedocs.io/en/latest/dev/contribution-guidelines-and-review.html),
+[writing documentation](https://empirical.readthedocs.io/en/latest/dev/adding-documentation.html), and
+[writing tests](https://empirical.readthedocs.io/en/latest/dev/guide-to-testing.html) are available in the documentation.
+
+Once you start working on a feature, we recommend making a pull request and giving it the "Merge: not ready" label. This way it's easy for everyone
+to keep tabs on ongoing Empirical development and the status of new features. Once you're done developing, remove the "Merge: not ready" label and
+add the "Merge: ready" label so that we know your pull request is ready for review.
+
+As part of your pull request, please add yourself to the list of contributors in the [license file](LICENSE.md).
+
+## Code of Conduct
+
+Please note we have a [code of conduct](CODE_OF_CONDUCT.md) and follow it in all your interactions with the project.
+
+## License
+
+By contributing, you agree that your contributions will be released under [Empirical's MIT License](LICENSE.md).
diff --git a/doc/LICENSE.md → LICENSE.md b/doc/LICENSE.md → LICENSE.md
@@ -1,11 +1,27 @@
-===============================================================================
-The MIT License (MIT)
+# The MIT License (MIT)
+
+Copyright (c) 2015-2023 Michigan State University Digital Evolution Laboratory
+
+Contributors: Charles Ofria,
+              Emily Dolson,
+              Jacob Fenton,
+              Riley Hoffman,
+              Steven Jorgensen,
+              Alex Lalejini,
+              Robin Miller,
+              Matthew Moreno,
+              Katherine Perry,
+              Santiago Rodriguez-Papa,
+              Oliver Baldwin Edwards,
+              Jason Stredwick,
+              Raheem Clemons,
+              Anya Vostinar,
+              Luis Zaman,
+              Ryan Moreno,
+              Nitash C G,
+              Jory Schossau,
+              and Dylan Rainbow
 
-Copyright (c) 2015-2020 Michigan State University
-Contributers: Charles Ofria, Emily Dolson, Jacob Fenton, Riley Hoffman,
-        Steven Jorgensen, Alex Lalejini, Robin Miller, Matthew Moreno,
-        Katherine Perry, Santiago Rodriguez-Papa, Jory Schossau,
-        Jason Stredwick, Anya Vostinar, and Luis Zaman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -57,31 +73,6 @@ OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-===============================================================================
-This repository also contains the source code for C3.js (https://github.com/c3js/c3), which is available
-under the MIT License:
-
-The MIT License (MIT)
-
-Copyright (c) 2013 Masayuki Tanaka
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
 ===============================================================================
 
 This repository also contains the source code for d3-tip.js (https://github.com/Caged/d3-tip), which is available
@@ -113,3 +104,11 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 This repository contains source code adapted from the LLVM Project, under the
 Apache License v2.0 with LLVM Exceptions. See https://llvm.org/LICENSE.txt for
 license information. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception.
+
+===============================================================================
+
+This repository also contains a Bloom filter class was written by Arash Partow (http://www.partow.net/programming/hashfunctions/index.html) and distributed under the MIT License. @copyright Arash Partow, 2000 (modified slightly by Emily Dolson)
+
+===============================================================================
+
+See directories within the third-party directory for information about the licenses dependencies are  under.
diff --git a/doc/dev/contribution-guidelines-and-review.md b/doc/dev/contribution-guidelines-and-review.md
@@ -161,19 +161,29 @@ Specific cases include:
 
 ## Checklist
 
-Copy and paste the following into a pull request comment when it is
-ready for review:
+To submit code to Empirical, open a Pull Request on Github. When you are ready for it to be reviewed, add the "Merge Ready" label. Before requesting a review, you should ensure that all checks on Github pass and confirm that the following automatically-checkable things are true:
 
-    - [ ] Is it mergeable?
-    - [ ] Did it pass the tests?
-    - [ ] Does the source code follow the Empirical coding standards?
-    - [ ] Has the code been commented (especially non-intuitive sections)
-    - [ ] Was a spellchecker run on the source code and documentation after
-      changes were made?
+- The code is merge-able into master (checked by Github)
+- All tests pass (checked by Github actions CI)
+- The documentation builds successfully (checked by readthedocs action and Github actions CI)
+
+You should also verify that the following are true. These cannot be manually checked, so copy and paste the following checklist into a pull request comment and check them off as you do them:
+
+    - [ ] The source code follows the Empirical coding standards
+    - [ ] The code been commented (especially non-intuitive sections)
+    - [ ] A spellchecker was run on the source code and documentation after changes were made?
+    - [ ] All newly added/modified code has high-quality tests associated with it (the CodeCov Github Automation will check this, but you should verify it)
+    - [ ] All newly-added functions and classes have doxygen-compatible docstrings
 
 It's expected that before requesting a code review the author of the PR
 will have checked all these things on their own. It's also expected
 that whomever reviews the PR will check these individual items as well.
-Though the CI runs most of these and will pass/fail the PR accordingly
-it is not infallible and the whole point of having a code review process
+The CI is not infallible and the whole point of having a code review process
 is to have human eyes go over the changes to the codebase.
+
+The code reviewer should verify that the above requirements are met, and also that:
+
+  - The code is well-organized
+  - The code is commented appropriately
+  - Any new tests are of acceptable quality
+  - The addition represents an improvement to Empirical
diff --git a/doc/requirements.in b/doc/requirements.in
@@ -1,6 +1,8 @@
-sphinx
-exhale
-sphinx-rtd-theme
-coverxygen
-breathe
-myst-parser
+sphinx==7.2.6
+sphinx-rtd-theme==2.0.0
+coverxygen==1.8.1
+breathe==4.35.0
+myst-parser==2.0.0
+sphinx-tippy==0.4.1
+sphinxcontrib-bibtex==2.6.1
+docutils==0.20.1