Skip to content

Commit

Permalink
Merge commit '14043a8c5aa7b0d3c163dcf3d5c32043087234c9' as '.lib/git-…
Browse files Browse the repository at this point in the history
…fleximod'
  • Loading branch information
jedwards4b committed Sep 25, 2024
2 parents c20866f + 14043a8 commit b0e0478
Showing 30 changed files with 3,359 additions and 0 deletions.
13 changes: 13 additions & 0 deletions .lib/git-fleximod/.github/workflows/pre-commit
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
name: pre-commit
on:
pull_request:
push:
branches: [main]

jobs:
pre-commit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v3
- uses: pre-commit/action@v3.0.0
80 changes: 80 additions & 0 deletions .lib/git-fleximod/.github/workflows/pytest.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Run this job on pushes to `main`, and for pull requests. If you don't specify
# `branches: [main], then this actions runs _twice_ on pull requests, which is
# annoying.

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

# If you wanted to use multiple Python versions, you'd have specify a matrix in the job and
# reference the matrixe python version here.
- uses: actions/setup-python@v5
with:
python-version: '3.12'

# Cache the installation of Poetry itself, e.g. the next step. This prevents the workflow
# from installing Poetry every time, which can be slow. Note the use of the Poetry version
# number in the cache key, and the "-0" suffix: this allows you to invalidate the cache
# manually if/when you want to upgrade Poetry, or if something goes wrong. This could be
# mildly cleaner by using an environment variable, but I don't really care.
- name: cache poetry install
uses: actions/cache@v4
with:
path: ~/.local
key: poetry-1.8.2

# Install Poetry. You could do this manually, or there are several actions that do this.
# `snok/install-poetry` seems to be minimal yet complete, and really just calls out to
# Poetry's default install script, which feels correct. I pin the Poetry version here
# because Poetry does occasionally change APIs between versions and I don't want my
# actions to break if it does.
#
# The key configuration value here is `virtualenvs-in-project: true`: this creates the
# venv as a `.venv` in your testing directory, which allows the next step to easily
# cache it.
- uses: snok/install-poetry@v1
with:
version: 1.8.2
virtualenvs-create: true
virtualenvs-in-project: true

# Cache your dependencies (i.e. all the stuff in your `pyproject.toml`). Note the cache
# key: if you're using multiple Python versions, or multiple OSes, you'd need to include
# them in the cache key. I'm not, so it can be simple and just depend on the poetry.lock.
- name: cache deps
id: cache-deps
uses: actions/cache@v4
with:
path: .venv
key: pydeps-${{ hashFiles('**/poetry.lock') }}

# Install dependencies. `--no-root` means "install all dependencies but not the project
# itself", which is what you want to avoid caching _your_ code. The `if` statement
# ensures this only runs on a cache miss.
- run: poetry install --no-interaction --no-root
if: steps.cache-deps.outputs.cache-hit != 'true'

# Now install _your_ project. This isn't necessary for many types of projects -- particularly
# things like Django apps don't need this. But it's a good idea since it fully-exercises the
# pyproject.toml and makes that if you add things like console-scripts at some point that
# they'll be installed and working.
- run: poetry install --no-interaction

# And finally run tests. I'm using pytest and all my pytest config is in my `pyproject.toml`
# so this line is super-simple. But it could be as complex as you need.
- run: |
git config --global user.name "${GITHUB_ACTOR}"
git config --global user.email "${GITHUB_ACTOR_ID}+${GITHUB_ACTOR}@users.noreply.github.com"
poetry run pytest
- name: Setup tmate session
if: ${{ failure() }}
uses: mxschmitt/action-tmate@v3

18 changes: 18 additions & 0 deletions .lib/git-fleximod/.pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
exclude: ^utils/.*$

repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.0.1
hooks:
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/psf/black
rev: 22.3.0
hooks:
- id: black
- repo: https://github.com/PyCQA/pylint
rev: v2.11.1
hooks:
- id: pylint
args:
- --disable=I,C,R,logging-not-lazy,wildcard-import,unused-wildcard-import,fixme,broad-except,bare-except,eval-used,exec-used,global-statement,logging-format-interpolation,no-name-in-module,arguments-renamed,unspecified-encoding,protected-access,import-error,no-member
107 changes: 107 additions & 0 deletions .lib/git-fleximod/CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# Contributor Code of Conduct
_The Contributor Code of Conduct is for participants in our software projects and community._

## Our Pledge
We, as contributors, creators, stewards, and maintainers (participants), of **git-fleximod** pledge to make participation in
our software, system or hardware project and community a safe, productive, welcoming and inclusive experience for everyone.
All participants are required to abide by this Code of Conduct.
This includes respectful treatment of everyone regardless of age, body size, disability, ethnicity, gender identity or expression,
level of experience, nationality, political affiliation, veteran status, pregnancy, genetic information, physical appearance, race,
religion, or sexual orientation, as well as any other characteristic protected under applicable US federal or state law.

## Our Standards
Examples of behaviors that contribute to a positive environment include:

* All participants are treated with respect and consideration, valuing a diversity of views and opinions
* Be considerate, respectful, and collaborative
* Communicate openly with respect for others, critiquing ideas rather than individuals and gracefully accepting criticism
* Acknowledging the contributions of others
* Avoid personal attacks directed toward other participants
* Be mindful of your surroundings and of your fellow participants
* Alert UCAR staff and suppliers/vendors if you notice a dangerous situation or someone in distress
* Respect the rules and policies of the project and venue

Examples of unacceptable behavior include, but are not limited to:

* Harassment, intimidation, or discrimination in any form
* Physical, verbal, or written abuse by anyone to anyone, including repeated use of pronouns other than those requested
* Unwelcome sexual attention or advances
* Personal attacks directed at other guests, members, participants, etc.
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Alarming, intimidating, threatening, or hostile comments or conduct
* Inappropriate use of nudity and/or sexual images
* Threatening or stalking anyone, including a participant
* Other conduct which could reasonably be considered inappropriate in a professional setting

## Scope
This Code of Conduct applies to all spaces managed by the Project whether they be physical, online or face-to-face.
This includes project code, code repository, associated web pages, documentation, mailing lists, project websites and wiki pages,
issue tracker, meetings, telecons, events, project social media accounts, and any other forums created by the project team which the
community uses for communication.
In addition, violations of this Code of Conduct outside these spaces may affect a person's ability to participate within them.
Representation of a project may be further defined and clarified by project maintainers.

## Community Responsibilities
Everyone in the community is empowered to respond to people who are showing unacceptable behavior.
They can talk to them privately or publicly.
Anyone requested to stop unacceptable behavior is expected to comply immediately.
If the behavior continues concerns may be brought to the project administrators or to any other party listed in the
[Reporting](#reporting) section below.

## Project Administrator Responsibilities
Project administrators are responsible for clarifying the standards of acceptable behavior and are encouraged to model appropriate
behavior and provide support when people in the community point out inappropriate behavior.
Project administrator(s) are normally the ones that would be tasked to carry out the actions in the [Consequences](#consequences)
section below.

Project administrators are also expected to keep this Code of Conduct updated with the main one housed at UCAR, as listed below in
the [Attribution](#attribution) section.

## Reporting
Instances of unacceptable behavior can be brought to the attention of the project administrator(s) who may take any action as
outlined in the [Consequences](#consequences) section below.
However, making a report to a project administrator is not considered an 'official report' to UCAR.

Instances of unacceptable behavior may also be reported directly to UCAR pursuant to [UCAR's Harassment Reporting and Complaint
Procedure](https://www2.fin.ucar.edu/procedures/hr/harassment-reporting-and-complaint-procedure), or anonymously through [UCAR's
EthicsPoint Hotline](https://www2.fin.ucar.edu/ethics/anonymous-reporting).

Complaints received by UCAR will be handled pursuant to the procedures outlined in UCAR's Harassment Reporting and Complaint
Procedure.
Complaints to UCAR will be held as confidential as practicable under the circumstances, and retaliation against a person who
initiates a complaint or an inquiry about inappropriate behavior will not be tolerated.

Any Contributor can use these reporting methods even if they are not directly affiliated with UCAR.
The Frequently Asked Questions (FAQ) page for reporting is [here](https://www2.fin.ucar.edu/procedures/hr/reporting-faqs).

## Consequences
Upon receipt of a complaint, the project administrator(s) may take any action deemed necessary and appropriate under the
circumstances.
Such action can include things such as: removing, editing, or rejecting comments, commits, code, wiki edits, email, issues, and
other contributions that are not aligned to this Code of Conduct, or banning temporarily or permanently any contributor for other
behaviors that are deemed inappropriate, threatening, offensive, or harmful.
Project administrators also have the right to report violations to UCAR HR and/or UCAR's Office of Diversity, Equity and Inclusion
(ODEI), as well as a participant's home institution and/or law enforcement.
In the event an incident is reported to UCAR, UCAR will follow its Harassment Reporting and Complaint Procedure.

## Process for Changes
All UCAR managed projects are required to adopt this Contributor Code of Conduct.
Adoption is assumed even if not expressly stated in the repository.
Projects should fill in sections where prompted with project-specific information, including, project name and adoption date.

Projects that adopt this Code of Conduct need to stay up to date with UCAR's Contributor Code of Conduct, linked with a DOI in the
[Attribution](#attribution) section below.
Projects can make limited substantive changes to the Code of Conduct, however, the changes must be limited in scope and may not
contradict the UCAR Contributor Code of Conduct.

## Attribution
This Code of Conduct was originally adapted from the [Contributor Covenant](http://contributor-covenant.org/version/1/4), version
1.4.
We then aligned it with the UCAR Participant Code of Conduct, which also borrows from the American Geophysical Union (AGU) Code of
Conduct.
The UCAR Participant Code of Conduct applies to both UCAR employees as well as participants in activities run by UCAR.
The original version of this for all software projects that have strong management from UCAR or UCAR staff is available on the UCAR
website at https://doi.org/10.5065/6w2c-a132.
The date that it was adopted by this project was **Feb/13/2018**.
When responding to complaints, UCAR HR and ODEI will do so based on the latest published version.
Therefore, any project-specific changes should follow the [Process for Changes](#process-for-changes) section above.
20 changes: 20 additions & 0 deletions .lib/git-fleximod/License
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
Copyright 2024 NSF National Center for Atmospheric Sciences (NCAR)

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.
108 changes: 108 additions & 0 deletions .lib/git-fleximod/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# git-fleximod

Flexible, Enhanced Submodule Management for Git

## Overview

Git-fleximod is a Python-based tool that extends Git's submodule and sparse checkout capabilities, offering additional features for managing submodules in a more flexible and efficient way.

## Installation

If you choose to locate git-fleximod in your path you can access it via command: git fleximod

## Usage

Basic Usage:
git fleximod <command> [options]
Available Commands:
status: Display the status of submodules.
update: Update submodules to the tag indicated in .gitmodules variable fxtag.
test: Make sure that fxtags and submodule hashes are consistant,
make sure that official urls (as defined by fxDONOTUSEurl) are set
make sure that fxtags are defined for all submodules
Additional Options:
See git fleximod --help for more details.

## Supported .gitmodules Variables

fxtag: Specify a specific tag or branch to checkout for a submodule.
fxrequired: Mark a submodule's checkout behavior, with allowed values:
- ToplevelRequired: Top-level and required (checked out only when this is the Toplevel module).
- ToplevelOptional: Top-level and optional (checked out with --optional flag if this is the Toplevel module).
- AlwaysRequired: Always required (always checked out).
- AlwaysOptional: Always optional (checked out with --optional flag).
fxsparse: Enable sparse checkout for a submodule, pointing to a file containing sparse checkout paths.
fxDONOTUSEurl: This is the url used in the test subcommand to assure that protected branches do not point to forks
**NOTE** the fxDONOTUSEurl variable is only used to identify the official project repository and should not be
changed by users. Use the url variable to change to a fork if desired.

## Sparse Checkouts

To enable sparse checkout for a submodule, set the fxsparse variable
in the .gitmodules file to the path of a file containing the desired
sparse checkout paths. Git-fleximod will automatically configure
sparse checkout based on this file when applicable commands are run.
See [git-sparse-checkout](https://git-scm.com/docs/git-sparse-checkout#_internalsfull_pattern_set)
for details on the format of this file.

## Tests

The git fleximod test action is designed to be used by, for example, github workflows
to assure that protected branches are consistant with respect to submodule hashes and fleximod fxtags

## Examples

Here are some common usage examples:

Update all submodules, including optional ones:
```bash
git fleximod update --optional
```

Updating a specific submodule to the fxtag indicated in .gitmodules:

```bash
git fleximod update submodule-name
```
Example .gitmodules entry:
```ini, toml
[submodule "cosp2"]
path = src/physics/cosp2/src
url = https://github.com/CFMIP/COSPv2.0
fxsparse = ../.cosp_sparse_checkout
fxrequired = AlwaysRequired
fxtag = v2.1.4cesm
```
Explanation:

This entry indicates that the submodule named cosp2 at tag v2.1.4cesm
should be checked out into the directory src/physics/cosp2/src
relative to the .gitmodules directory. It should be checked out from
the URL https://github.com/CFMIP/COSPv2.0 and use sparse checkout as
described in the file ../.cosp_sparse_checkout relative to the path
directory. It should be checked out anytime this .gitmodules entry is
read.

Additional example:
```ini, toml
[submodule "cime"]
path = cime
url = https://github.com/jedwards4b/cime
fxrequired = ToplevelRequired
fxtag = cime6.0.198_rme01
```

Explanation:

This entry indicates that the submodule cime should be checked out
into a directory named cime at tag cime6.0.198_rme01 from the URL
https://github.com/jedwards4b/cime. This should only be done if
the .gitmodules file is at the top level of the repository clone.

## Contributing

We welcome contributions! Please see the CONTRIBUTING.md file for guidelines.

## License

Git-fleximod is released under the MIT License.
20 changes: 20 additions & 0 deletions .lib/git-fleximod/doc/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
26 changes: 26 additions & 0 deletions .lib/git-fleximod/doc/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "git-fleximod"
author = "Jim Edwards <jedwards@ucar.edu>"
release = "0.4.0"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ["sphinx_argparse_cli"]

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "alabaster"
html_static_path = ["_static"]
Loading

0 comments on commit b0e0478

Please sign in to comment.