Skip to content

Commit

Permalink
docs: pre-commit dev docs
Browse files Browse the repository at this point in the history
  • Loading branch information
aaraney authored and christophertubbs committed Jul 31, 2024
1 parent edd8caa commit d41a943
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 1 deletion.
2 changes: 1 addition & 1 deletion INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ The `./scripts/control_stack.sh` script will automatically create directories an

## Installing Python and Path Verification

As noted in the [dependencies](doc/DEPENDENCIES.md), Python, the Python development package, and Pip should be installed in the appropriate manner for your environment.
As noted in the [dependencies](doc/DEPENDENCIES.md), Python, the Python development package, Pip, and pre-commit should be installed in the appropriate manner for your environment.

### Different Python Executable Names
It is quite common for the Python executables to be named `python3`, `python311`, `pip3`, etc. in the *global* Python environment, instead of just `python` and `pip`. This is accounted for when [creating a virtual environment](#using-a-virtual-environment), provided the right Python command was used to create it. Users not doing this should consider setting up shell aliases, symlinks in their path, or some other mechanism to ensure `python` and `pip` execute the desired versions appropriately.
Expand Down
1 change: 1 addition & 0 deletions doc/DEPENDENCIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ The DMOD project has two related sets of dependencies:
| Python Development Headers/Libs | Analogous to installed Python version | Required for building certain Python dependency wheels; e.g., *pandas* |
| C++ Compiler | | Required for building certain Python dependency wheels; e.g., *pandas* |
| Python Packages | See [requirements.txt](../requirements.txt) | Recommend installing in Python virtual environment |
| pre-commit | See [.pre-commit-config.yaml](../.pre-commit-config.yaml) | Recommend installing in Python virtual environment |

## Dependency Caveats
The strictness of these dependencies can vary in different situations, in a way that is hard to define concisely. E.g., one could probably avoid installing Bash by manually performing all the tasks handled by Bash scripts [^1]. Also, OpenSSL is not needed (locally) if all required SSL certificates can be provided from elsewhere. And somewhat related: multi-node deployments probably don't need ***all*** dependencies on the non-primary node(s).
Expand Down
25 changes: 25 additions & 0 deletions gitflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,31 @@ OR

Development work should commit frequently when changes are complete and meaningful. If work requires modifying more than one file in the source, it is recommended to commit the changes independently to help avoid too large of conflicts if the occur.

### Setting up `pre-commit` hooks

[`pre-commit`](https://pre-commit.com/) is used to manage and install `git` pre-commit hooks.
pre-commit hooks run automatically when `git commit` is invoked and perform checks on the code you are committing.
Example checks are removing trailing white spaces, verifying that large files are not included, or running a code linting tool.
Hooks are configured in the [`.pre-commit-config.yaml`](./.pre-commit-config.yaml) file in the root of the repo.

`pre-commit` can be installed using a package manager (e.g. `brew install pre-commit`) or from `pip`.
If you are to use `pip`, it is highly recommend to use a virtual environment.

Install pre-commit hooks into your `git` clone by running:

```shell
pre-commit install
```

Hooks will now run when code is committed.
Alternatively, you can run the pre-commit hooks manually via:

```shell
pre-commit run --all-files
```

For more information, see [`pre-commit`'s documentation](https://pre-commit.com/index.html).

### Commits

When changes are made to a file and ready for committing, then use these git commands
Expand Down

0 comments on commit d41a943

Please sign in to comment.