From 5b1cfe7ffd5541b8c31e7cdf76a66f0db3e9526e Mon Sep 17 00:00:00 2001 From: "Jason M. Gates" Date: Wed, 14 Feb 2024 16:49:48 -0700 Subject: [PATCH] docs: Update Markdown files for the move to GitHub --- CONTRIBUTING.md | 665 ++++++++++++++++++++++++++++++++++-------------- README.md | 118 +++++---- SECURITY.md | 10 +- 3 files changed, 546 insertions(+), 247 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8126c6..70954f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,142 +1,448 @@ -# Contributing to ShellLogger +# Contributing to shell-logger -Thanks so much for your willingness to help out with `ShellLogger`'s +Thanks so much for your willingness to help out with `shell-logger`'s development :grinning: Here's everything you need to know. -
-Contents - -
- - - -## Getting Started - -Before you begin hacking on `ShellLogger`, you'll need to do three things: - -1. **Request Access:** On [`ShellLogger`'s project - page](https://internal.gitlab.server/ShellLogger/ShellLogger) you should see - a button to request access to the project. When you request access, a - project maintainer will first give you [**Reporter** - permissions](https://docs.gitlab.com/ee/user/permissions.html). -2. **Fork the Repository:** Again on [`ShellLogger`'s project - page](https://internal.gitlab.server/ShellLogger/ShellLogger), in the - top-right corner, you'll see a button to [fork the - repository](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork). + + +## Setting Up Your Environment + +Before you begin hacking on `shell-logger`, you'll need to do four things: + +1. **Fork the Repository:** On [`shell-logger`'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@internal.gitlab.server:${USER}/ShellLogger - cd ShellLogger - git remote add upstream git@internal.gitlab.server:ShellLogger/ShellLogger + git clone git@github.com:${USER}/shell-logger + cd shell-logger + git remote add upstream git@github.com:sandialabs/shell-logger git fetch upstream ``` -3. **Set Up your Environment:** Install the requirements with +2. **Set Up your Environment:** Install the requirements with ```bash - cd /path/to/ShellLogger + cd /path/to/shell-logger python3 -m pip install \ -r requirements.txt \ - -r tests/requirements.txt \ - -r doc/requirements.txt + -r doc/requirements.txt \ + -r example/requirements.txt \ + -r test/requirements.txt ``` - - Make sure you can run the test suite with +3. **Run the Examples:** Ensure you can run all the examples with ```bash - python3 -m pytest tests/ + cd /path/to/shell-logger/example + ./run-all.bash ``` - - and that you can build the documentation with +4. **Build the Documentation:** Ensure you can build the documentation with ```bash - cd doc - bash make_html_docs.sh + cd /path/to/shell-logger/doc + ./make-html.bash ``` -If you're able to do all the above successfully, then you're ready to start -work. +[homepage]: https://github.com/sandialabs/shell-logger +[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo + +### Pre-Commit + +We use [pre-commit][precommit] to ensure adherence to Python best 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/shell-logger +pre-commit install +pre-commit install --hook-type commit-msg --hook-type pre-push +``` + +[precommit]: https://pre-commit.com/ + +The checks we perform are the following: +* Use [commitizen][commitizen] to ensure commit messages match the + [Conventional Commits specification][conventional]. Use the + [Conventional Commits extension for VS Code][extension] (or something + similar) to create commit messages that match the standard. +* Use [mypy][mypy] to run static type checking on our type-hinted code. +* Ensure no large files are added to the repository. +* Ensure files parse as valid Python. +* 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. +* Ensure test files are correctly named. +* Trim trailing whitespace. +* Ensure we use [type-hinting][typing]. +* Check for common mistakes in [reStructuredText][rest] in our documentation. +* Use [black][black] to automatically format the code. +* Use [Bandit][bandit] to find common security issues. +* Use [doc8][doc8] to enforce our style for our documentation. +* Lint the code with [flake8][flake8]. +* Use [isort][isort] to ensure `import` statements are sorted correctly. +* Use [prospector][prospector] to check for various errors, potential problems, + convention violations, complexity, etc. This uses the following tools under + the hood: + * [dodgy][dodgy] + * [mccabe][mccabe] + * [pycodestyle][pycodestyle] + * [Pyflakes][pyflakes] + * [Pylint][pylint] +* Use [pydocstyle][pydocstyle] to ensure our docstrings line up with + [PEP 257][pep257]. +* Use [pyroma][pyroma] to ensure our package complies with the best practices + of the Python packaging ecosystem. + +[commitizen]: https://github.com/commitizen-tools/commitizen +[conventional]: https://www.conventionalcommits.org/en/v1.0.0/ +[extension]: https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits +[mypy]: https://github.com/python/mypy +[typing]: https://docs.python.org/3/library/typing.html +[black]: https://github.com/psf/black +[bandit]: https://github.com/PyCQA/bandit +[doc8]: https://github.com/PyCQA/doc8 +[flake8]: https://github.com/pyCQA/flake8 +[isort]: https://github.com/pyCQA/isort +[prospector]: https://github.com/landscapeio/prospector +[dodgy]: https://github.com/landscapeio/dodgy +[mccabe]: https://github.com/PyCQA/mccabe +[pycodestyle]: https://pycodestyle.pycqa.org/en/latest/ +[pyflakes]: https://launchpad.net/pyflakes +[pylint]: https://www.pylint.org/ +[pydocstyle]: https://github.com/PyCQA/pydocstyle +[pep257]: http://www.python.org/dev/peps/pep-0257/ +[pyroma]: https://github.com/regebro/pyroma + +### 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 +* [Python Development in Visual Studio Code][pyvscode] from + [RealPython.com][realpython] +* [Advanced Visual Studio Code for Python Developers][advanced] from + [RealPython.com][realpython] +* 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 +[pyvscode]: https://realpython.com/python-development-visual-studio-code/ +[realpython]: http://realpython.com/ +[advanced]: https://realpython.com/advanced-visual-studio-code-python/ +[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. +* **GitLab Workflow:** Integrate GitLab issues, merge requests, and pipelines + into VS Code. +* **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 Adapter Converter:** Converts from the Test Explorer UI (below) API + to native VS Code testing. +* **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. + +[kraken]: https://www.gitkraken.com/ + +**Python-Specific** +* **AREPL for python:** Automatically evaluate Python code as you type in the + editor. +* **autoDocstring - Python Docstring Generator:** Quickly generate docstrings + for Python functions. +* **Flake8:** Linting support for Python files using flake8. +* **Pylance:** Fast, feature-rich language support for Python. +* **Pylint:** Linting support for Python files. +* **Pytest IntelliSense:** Adds IntelliSense support for [pytest][pytest] + fixtures. +* **Python:** Rich support for the Python language. +* **Python Indent:** Correct Python indentation. +* **Python Test Explorer:** Run your [unittest][unittest], [pytest][pytest], + or [testplan][testplan] tests with the Test Explorer UI (see **General** + above). +* **Python Type Hint:** Type hint autocompletion. +* **Sourcery:** Automatic code review and refactoring. + +[unittest]: https://docs.python.org/3/library/unittest.html +[testplan]: https://github.com/morganstanley/testplan + +#### 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". + * Python + * **Formatting:** Provider: Select "black". + * **Linting: Bandit Enabled:** Check. + * **Linting: Flake8 Enabled:** Check. + * **Linting: Lint On Save:** Check. + * **Linting: Mypy Enabled:** Check. + * **Linting: Prospector Enabled:** Check. + * Python Docstring Generator configuration + * **Docstring Format:** Select "google-notypes". + * **Start On New Line:** Check. + * Sourcery Configuration: + * **Token:** [Create a free Sourcery account][sourcery], generate a token, + and paste it here. + * Vim + * **Vimrc:** Enable: Check. + +[hack]: https://github.com/gaplo917/Ligatured-Hack +[sourcery]: https://sourcery.ai/ + +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 + ], + ``` + The line at 79 characters is to remind you of the maximum line length, and + the one at 72 characters is to remind you of the maximum line length for + comments and docstrings (see [PEP8][pep8]). +* To prevent VS Code from sending telemetry data off-site, add + ```json + "redhat.telemetry.enabled": false, + ``` +* 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, + ``` +* To set up `pytest`, such that it produces coverage information, add + ```json + "python.testing.unittestEnabled": false, + "python.testing.pytestEnabled": true, + "python.testing.pytestArgs": [ + "-v", + "--cov", + "--cov-report=html", + "--cov-report=json", + "--cov-report=xml", + "." + ], + ``` + +[pep8]: https://peps.python.org/pep-0008/#maximum-line-length + +A final setting needs to be configured in the [`launch.json` file][launchjson]. +You'll need to add the following to the list of configurations: +```json +"configurations": [ + { + ... # Existing configuration. + }, + { + "name": "Python: Debug Tests", + "type": "python", + "request": "launch", + "program": "${file}", + "purpose": ["debug-test"], + "console": "integratedTerminal", + "env": { + "PYTEST_ADDOPTS": "--no-cov" + }, + "justMyCode": false + } +] +``` +This will make it such that when debugging unit testing, the debugger doesn't +restrict itself to only your code. + +[launchjson]: https://code.visualstudio.com/docs/editor/debugging#_launch-configurations + +#### Choosing a Python Interpreter + +Once you've taken care of all the settings above, you're almost ready to start +Python development with VS Code. Before you do, though, you'll need to select +your Python interpreter. Open the command palette, start typing "python +interpreter," and select **Python: Select Interpreter**. It will pop up a list +of Python installations it could find on your system. Pick the one that +corresponds to your development environment (see +[above](#setting-up-your-environment)). + +#### Setting Up PyTest + +The last step in setting up VS Code for Python development is to ensure +`pytest` is working. Click on the flask icon on the left-hand side to open the +**TESTING** panel on the left. There will be two collapsible sections labeled +**TEST EXPLORER**. Collapse the top one (it comes from an extension that +doesn't quite work for Python testing), and expand the bottom one. You should +be able to hover over a test file, click the play button, and see the tests +pass. If so, go ahead and click the three dots at the top-right of the +**TESTING** panel and deselect the top **Test Explorer**. + +Running your test suite will generate code coverage information, which you can +then view in the editor. After you've run your tests, open up one of your code +files, open the command palette, type "coverage," and select +**Coverage-Gutters: Toggle Coverage**. This will highlight covered and +uncovered lines in green and red, respectively. You can also view the full +coverage report by opening `test/htmlcov/index.html`. + + + +## 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 + +Classes and functions should be documented with [docstrings][docstrings] using +the [Google-style][google] format. The contents of docstrings should use +[reStructuredText][rest] formatting. This is so we can use [Sphinx][sphinx] to +generate [our documentation][docs]. Additionally, function definitions should +utilize [type-hinting][typing] wherever possible for clarity's sake. + +[docstrings]: https://www.python.org/dev/peps/pep-0257 +[google]: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings +[rest]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +[docs]: https://shell-logger.readthedocs.io +[sphinx]: https://www.sphinx-doc.org/en/master/ + +### Testing + +We use [pytest][pytest] for our unit test suite. To get up-to-speed with what +it does and how it works, check out [this RealPython tutorial][tutorial]. Also +highly recommended is [Python Testing with pytest, by Brian Okken][okken]. + +[pytest]: https://docs.pytest.org/ +[tutorial]: https://realpython.com/pytest-python-testing/ +[okken]: https://www.amazon.com/Python-Testing-pytest-Effective-Scalable/dp/1680502409/ref=sr_1_2?keywords=pytest&qid=1637712723&sr=8-2 + +Please add tests to cover any new functions you create, and adhere to the +following guidelines: +* Each module (`module_name.py`) should have a corresponding test file + (`test_module_name.py`). +* Each function/method in a module should have at least one corresponding test. +* The test order should match the ordering of the functions/methods being + tested in the module, such that users can easily scroll through the two files + side-by-side. +* Prefer parametrizing a test function over creating a separate test function. +* But don't go too crazy with that—use your judgment. +* Place any fixture definitions at the top of the test file. + +### Best Practices + +* Docstrings and comments should be grammatically correct English + (capitalization, punctuation, full sentences, etc.). +* Prefer double quotes over single quotes. +* Use `pathlib.Path` and associated methods to represent all path-like objects. +* Use [f-strings][fstrings] for formatting strings. +* Alphabetize class attributes in the docstring and `__init__()` to ease + readability/maintainability/extensibility. +* Prefer alphabetizing keyword arguments to functions, unless a different + ordering would be more logical in a specific situation. +* Blank lines in functions should be avoided unless preceding a comment + indicating a section of code. However, if your function is broken up into + sections via comments, consider subdividing it into smaller functions. +* Prefer imports of the form + ```python + from package import Class + ``` + as opposed to + ```python + import package + ``` + if only using a small handful of things from the package. + +[fstrings]: https://peps.python.org/pep-0498/ ## Creating Issues -Create [issues](https://docs.gitlab.com/ee/user/project/issues/) in GitLab for -any work that needs to be done. Newly-created issues will automatically go in -the **Open** column on the [Kanban -board](https://internal.gitlab.server/ShellLogger/ShellLogger/-/boards). +Create [issues][issues] in GitHub for any work that needs to be done. + +[issues]: https://github.com/sandialabs/shell-logger/issues ### Markdown -[Markdown](https://en.wikipedia.org/wiki/Markdown) is a lightweight markup -language with plain text formatting syntax. GitLab uses a form of it for -rendering issue and merge request -[descriptions](https://docs.gitlab.com/ee/user/project/issues/issue_data_and_actions.html#description) -and [comments](https://docs.gitlab.com/ee/user/project/issues/issue_data_and_actions.html#comments), -[wiki pages](https://docs.gitlab.com/ee/user/project/wiki/), and -any files in your repositories with a `.md` extension (such as this one). For -more details on what's possible with GitLab-flavored Markdown, [see GitLab's -documentation on it](https://docs.gitlab.com/ee/user/markdown.html). +[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]. -### Issue Templates +[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 -In the top-left of the page when creating an issue, use the drop-down menu to -select a [description -template](https://docs.gitlab.com/ee/user/project/description_templates.html) -(~"Type :: Bug", ~"Type :: Discussion", ~"Type :: Documentation", -~"Type :: Feature", ~"Type :: Question", ~"Type :: Refactor", -~"Type :: Security", or ~"Type :: Task"). Follow the instructions that appear -in the template. - -### Linked Issues +### Issue Templates -Once an issue has been created, a [**Linked -issues**](https://docs.gitlab.com/ee/user/project/issues/related_issues.html) -box will appear below the issue description. You can use this feature to -indicate which issues are connected to each other, blocked by one another, etc. +When creating an issue, select one of the available issue templates, and then +follow the instructions that appear in the template. ### Labels -The [ShellLogger > -Labels](https://internal.gitlab.server/ShellLogger/ShellLogger/-/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 how the issue flows through our -[Kanban board](https://internal.gitlab.server/ShellLogger/ShellLogger/-/boards). -Other labels can be added as appropriate. +The [shell-logger > 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/shell-logger/labels @@ -144,24 +450,20 @@ Other labels can be added as appropriate. ### Planning Work -Depending on the needs of the `ShellLogger` user base, a project maintainer -will schedule issues to be tackled in the near future by dragging them into the -~"Stage :: Soon" column of the [Kanban -board](https://internal.gitlab.server/ShellLogger/ShellLogger/-/boards). An -issue can then be grabbed by a member of the development team when they have -some time available to work on it. +Depending on the needs of the `shell-logger` 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" column; just work on it as per the rest of the guidelines -> below. +> 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 move the issue to ~"Stage :: Development" on the [Kanban -board](https://internal.gitlab.server/ShellLogger/ShellLogger/-/boards). Next -make sure your local `master` branch is up-to-date with +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 @@ -173,10 +475,10 @@ git pull --ff-only upstream master Once `master` is updated, you then create a feature branch off of it with ```bash -git checkout -b +git checkout -b ``` -The recommended branch naming convention is to use the issue number, following +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 @@ -185,60 +487,38 @@ 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 either the [Conventional Commit plugin -for Pycharm](https://plugins.jetbrains.com/plugin/13389-conventional-commit) or -the [Conventional Commits extension for VS -Code](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits) -(or something similar) to ensure your commit messages adhere to the -[Conventional Commits -specification](https://www.conventionalcommits.org/en/v1.0.0/). +work into logical, working commits. Use the +[Conventional Commits extension for VS Code][vscode] (or something similar) to +ensure your commit messages adhere to the +[Conventional Commits specification][conventionalcommits]. + +[vscode]: https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits +[conventionalcommits]: https://www.conventionalcommits.org/en/v1.0.0/ Feel free to commit and push small chunks early and often and then use `git rebase -i` 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 with -> `git push origin +`. That is permissible (even encouraged), but +> `git push origin +`. 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. -#### Commit Messages - -Make sure your commit messages reference the appropriate issue numbers using -the `#` syntax. The first line of the commit message should be a -descriptive title, limited to 50 characters. This is then followed by a blank -line, and then the rest of the commit message is a description of the changes, -particularly *why* they were made, limited to 72 characters wide. - -#### pytest - -`ShellLogger` uses [pytest](https://docs.pytest.org/) for our unit test suite. -Please add tests to cover any new functions you create. - -#### Sphinx - -`ShellLogger` uses [Sphinx](https://www.sphinx-doc.org/en/master/) to generate -[our documentation](http://shelllogger.internal.gitlab.pages/ShellLogger). You'll -want to be familiar with the [Google docstring -format](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) -and [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) -for the sake of updating our documentation while changing the code itself. - ### When Work is Complete -While working on your feature in your local `` branch, other +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 checkout git rebase master ``` though there are others that are equally valid. Once all is well, create a -merge request (see below). +pull request (see below). ### Closing Old Issues @@ -249,38 +529,56 @@ comments some explanation as to why the issue won't be addressed. -## Merge Requests +## Pull Requests -The only way changes get into `master` is through merge requests. When you've +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 merge request. Remove whatever "Stage" -label GitLab automatically applies, as those only apply to issues. On the -[Kanban board](https://internal.gitlab.server/ShellLogger/ShellLogger/-/boards), -drag your issue into ~"Stage :: Review". +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". ### Reviewers -We recommend having your merge request reviewed by at least two other team -members. The first should be someone who is knowledgeable about the code that -you're changing—this is to make sure you don't accidentally do something -foolish. The second should be someone who knows little about the code you're -touching—this is to spread the knowledge of how the code works throughout -the team. Work with your reviewers to get your changes into an acceptable -state. +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 merge request as usual, but -insert "Draft:" at the beginning of the title (there will be a link to click to -do this for you). GitLab will not allow you to merge a draft request. - -### GitLab CI - -GitLab CI will automatically run on your merge request. The configuration for -the pipeline can be found in [the `.gitlab-ci.yml` -file](https://internal.gitlab.server/ShellLogger/ShellLogger/-/blob/master/.gitlab-ci.yml) -in the repository root. +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: +* **Continuous Integration:** This workflow runs a `test` job, parametrized + across the currently maintained versions of Python, to ensure unit testing + passes, and a `commits` job to ensure we're adhering to the [Conventional + Commits specification][conventional]. +* **Semantic Release:** This workflow runs on merges to `master` to + automatically generate and publish new releases, based on the commits just + merged. + +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. +* [ReadTheDocs][readthedocs]: We ensure our documentation builds for all PRs, + and the documentation is published for `master` and all release tags. +* [pre-commit.ci][precommitci]: We ensure all the `pre-commit` checks we + encourage developers to run locally also run in CI. + +[codecov]: https://about.codecov.io/ +[readthedocs]: https://about.readthedocs.com/?ref=readthedocs.org +[precommitci]: https://pre-commit.ci/ ### Merging @@ -288,15 +586,8 @@ 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 merge request, it's fine for those to be preserved in + 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. - -> **Note:** After making it through your first successful merge request into -> `ShellLogger`, you'll likely be upgraded from **Reporter** to [**Developer** -> permissions](https://docs.gitlab.com/ee/user/permissions.html). Once that -> happens, you can work in the repository itself and no longer need your fork -> (unless you prefer to continue working in it). Any references to `upstream` -> above can be replaced with `origin`. Welcome to the team :grinning: diff --git a/README.md b/README.md index 5dc712c..737f787 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,93 @@ -[![pipeline status](https://internal.gitlab.server/ShellLogger/ShellLogger/badges/master/pipeline.svg)](https://internal.gitlab.server/ShellLogger/ShellLogger/pipelines) -[![coverage report](https://internal.gitlab.server/ShellLogger/ShellLogger/badges/master/coverage.svg)](http://shelllogger.internal.gitlab.pages/ShellLogger/htmlcov) -[![documentation](https://img.shields.io/badge/docs-latest-green.svg)](http://shelllogger.internal.gitlab.pages/ShellLogger) +> **WARNING:** *This package is still in the process of being open sourced. +> Until that work is done and this banner is removed, don't expect anything +> documented here to work.* + +[![Code Style: black](https://img.shields.io/badge/Code%20Style-black-000000.svg)](https://github.com/psf/black) +[![codecov](https://codecov.io/gh/sandialabs/shell-logger/branch/master/graph/badge.svg?token=FmDStZ6FVR)](https://codecov.io/gh/sandialabs/shell-logger) +[![CodeQL](https://github.com/sandialabs/shell-logger/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/sandialabs/shell-logger/actions/workflows/github-code-scanning/codeql) +[![Conda Version](https://img.shields.io/conda/v/conda-forge/shell-logger?label=conda-forge)](https://anaconda.org/conda-forge/shell-logger) +![Conda Downloads](https://img.shields.io/conda/d/conda-forge/shell-logger?label=conda-forge%20downloads) +[![Continuous Integration](https://github.com/sandialabs/shell-logger/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/sandialabs/shell-logger/actions/workflows/continuous-integration.yml) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) - -# ShellLogger - -The `shelllogger` Python module allows you to interact with the shell, while +[![GitHub contributors](https://img.shields.io/github/contributors/sandialabs/shell-logger.svg)](https://github.com/sandialabs/shell-logger/graphs/contributors) +[![Documentation Status](https://readthedocs.org/projects/shell-logger/badge/?version=latest)](https://shell-logger.readthedocs.io/en/latest/?badge=latest) +[![Anaconda-Server Badge](https://anaconda.org/conda-forge/shell-logger/badges/license.svg)](LICENSE.md) +[![Linting: Pylint](https://img.shields.io/badge/Linting-Pylint-yellowgreen)](https://github.com/pylint-dev/pylint) +[![Merged PRs](https://img.shields.io/github/issues-pr-closed-raw/sandialabs/shell-logger.svg?label=merged+PRs)](https://github.com/sandialabs/shell-logger/pulls?q=is:pr+is:merged) +[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/1234567890/badge)](https://bestpractices.coreinfrastructure.org/projects/1234567890) +![Anaconda-Server Badge](https://anaconda.org/conda-forge/shell-logger/badges/platforms.svg) +[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) +[![pre-commit.ci Status](https://results.pre-commit.ci/badge/github/sandialabs/shell-logger/master.svg)](https://results.pre-commit.ci/latest/github/sandialabs/shell-logger/master) +[![PyPI - Version](https://img.shields.io/pypi/v/shell-logger?label=PyPI)](https://pypi.org/project/shell-logger/) +![PyPI - Downloads](https://img.shields.io/pypi/dm/shell-logger?label=PyPI%20downloads) +![Python Version](https://img.shields.io/badge/Python-3.8|3.9|3.10|3.11|3.12-blue.svg) +[![Security: Bandit](https://img.shields.io/badge/Security-Bandit-yellow.svg)](https://github.com/PyCQA/bandit) + +# shell-logger + +The `shell-logger` Python package allows you to interact with the shell, while logging various metadata, statistics, and trace information. Any time you're tempted to write your own wrapper around things like `subprocess.Popen()` or -`subprocess.run()`, consider using `shelllogger.ShellLogger.log()` instead. If -you're familiar with [the Unix script -command](https://man7.org/linux/man-pages/man1/script.1.html), this is similar -in principle, but with substantially more functionality. If you're familiar -with [Python's logging module](https://docs.python.org/3/library/logging.html), -the motivation is similar, but this intends to capture what's happening *in the -shell* rather than in Python itself. +`subprocess.run()`, consider using `shell_logger.ShellLogger.log()` instead. +If you're familiar with [the Unix script command][script], this is similar in +principle, but with substantially more functionality. If you're familiar with +[Python's logging module][logging], the motivation is similar, but this intends +to capture what's happening *in the shell* rather than in Python itself. + +[script]: https://man7.org/linux/man-pages/man1/script.1.html +[logging]: https://docs.python.org/3/library/logging.html ## Installation -To get up and running with `ShellLogger`, do the following: +To get up and running with `shell-logger`, simply: ```bash -git clone git@internal.gitlab.server:ShellLogger/ShellLogger -cd ShellLogger -python3 -m pip install . +python3 -m pip install shell-logger ``` -> **Note:** You may want to install the package in a separate Python -> environment, using either -> [conda](https://conda.io/projects/conda/en/latest/user-guide/concepts/environments.html) -> or [venv](https://docs.python.org/3/tutorial/venv.html). - ## Usage Once the package is installed, you can simply ```python -from shelllogger import ShellLogger +from shell_logger import ShellLogger sl = ShellLogger("Title of Log File") sl.log("Execute my first command in the shell.", "echo 'Hello World'") ``` -For more detailed usage and API information, please see [our -documentation](http://shelllogger.internal.gitlab.pages/ShellLogger). +For more detailed usage and API information, please see +[our documentation][readthedocs]. -## Adding `ShellLogger` as a Requirement for your Package - -If you'll be developing a package that will use `ShellLogger`, we recommend -adding this to your `requirements.txt` file -``` -shelllogger @ git+https://internal.gitlab.server/ShellLogger/ShellLogger@master#egg=shelllogger -``` - -replacing `master` with whatever git reference you like, and then using `pip -install -r requirements.txt` to handle installing it. +[readthedocs]: https://shell-logger.readthedocs.io ## Where to Get Help -If you're having trouble with `ShellLogger`, or just want to ask a question, -head on over to [our issue -board](https://internal.gitlab.server/ShellLogger/ShellLogger/-/issues). If a -quick search doesn't yield what you're looking for, feel free to file a -~"Type :: Question" issue. +If you're having trouble with `shell-logger`, or just want to ask a question, +head on over to [our issue board][issues]. If a quick search doesn't yield +what you're looking for, feel free to file an issue. + +[issues]: https://github.com/sandialabs/shell-logger/issues ## Contributing -If you're interested in contributing to the development of `ShellLogger`, we'd -love to have your help :grinning: Check out our [contributing -guidelines](https://internal.gitlab.server/ShellLogger/ShellLogger/-/blob/master/CONTRIBUTING.md) -for how to get started. [Past -contributors](https://internal.gitlab.server/ShellLogger/ShellLogger/-/graphs/master) -include: -* @josbrau -* @mswan -* @dcollin -* @jmgate +If you're interested in contributing to the development of `shell-logger`, we'd +love to have your help :grinning: Check out our +[contributing guidelines](CONTRIBUTING.md) for how to get started. +[Past contributors][contributors] include: +* [@bbraunj](https://github.com/bbraunj) +* Scot Swan +* [@dc-snl](https://github.com/dc-snl) +* [@jmgate](https://github.com/jmgate) +* [@mvlopri](https://github.com/mvlopri) + +[contributors]: https://github.com/sandialabs/shell-logger/graphs/contributors ## License -License information will be added after `ShellLogger` makes it through Sandia's -open-sourcing process. +See [LICENSE.md](LICENSE.md). ## Credits Special thanks to the EMPIRE project for investing in the initial development -of this tool, and [the GMS -project](https://internal.corporate.wiki/display/gmswiki/Geophysical+Monitoring+System+Wiki) -for serving as a second user and contributing to its clean-up. +of this tool, and [the GMS project][gms] for serving as a second user and +contributing to its clean-up. + +[gms]: https://github.com/SNL-GMS/GMS-PI21-OPEN/ diff --git a/SECURITY.md b/SECURITY.md index d1ad5bf..acb6b86 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,8 @@ # Security Vulnerabilities -If you discover a security vulnerability in `ShellLogger`, please file an issue -using the ~"Type :: Security" issue template. See [our contributing -guidelines](CONTRIBUTING.md) for details. We thank you in advance for helping -to improve the security of this package. +If you discover a security vulnerability in `shell-logger`, please head on +over to the [Security Advisories page][advisories] and +draft a new advisory. We thank you in advance for helping to improve the +security of this package. + +[advisories]: https://github.com/sandialabs/shell-logger/security/advisories