From 6de344428d98e5277b4a9ca495577ddfad08db0e Mon Sep 17 00:00:00 2001 From: David Brownell Date: Tue, 4 Jun 2024 13:53:46 -0400 Subject: [PATCH] Changes to increase www.bestpractices.dev/ score After these changes, a repository based on this template will score 58% on https://www.bestpractices.dev/. - Updated `.manifest.yml` header to include name and url - Bumped CI dependencies from 0.15.6 to 0.17.0 --- .github/workflows/standard.yaml | 16 ++--- .../ProjectGenerationUtils.py | 15 +++-- .../.github/workflows/standard.yaml | 18 +++--- .../CONTRIBUTING.md | 58 +++++++++++++++++++ .../{{ cookiecutter.__empty_dir }}/README.md | 35 +++++++++-- .../SECURITY.md | 9 +++ 6 files changed, 124 insertions(+), 27 deletions(-) create mode 100644 src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md create mode 100644 src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/SECURITY.md diff --git a/.github/workflows/standard.yaml b/.github/workflows/standard.yaml index 1d18bd5..d1ac592 100644 --- a/.github/workflows/standard.yaml +++ b/.github/workflows/standard.yaml @@ -23,7 +23,7 @@ jobs: # ---------------------------------------------------------------------- action_contexts: name: "Display GitHub Action Contexts" - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_display_action_contexts.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_display_action_contexts.yaml@CI-v0.17.0 # ---------------------------------------------------------------------- validate: @@ -45,7 +45,7 @@ jobs: name: Validate - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python.yaml@CI-v0.17.0 with: operating_system: ${{ matrix.os }} python_version: ${{ matrix.python_version }} @@ -56,7 +56,7 @@ jobs: name: Postprocess Coverage Info - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_package_python_coverage.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_package_python_coverage.yaml@CI-v0.17.0 with: gist_id: 2f9d770d13e3a148424f374f74d41f4b gist_filename: PythonProjectBootstrapper_coverage.json @@ -85,7 +85,7 @@ jobs: name: Create Package - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_package.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_package.yaml@CI-v0.17.0 with: operating_system: ${{ matrix.os }} python_version: ${{ matrix.python_version }} @@ -112,7 +112,7 @@ jobs: name: Validate Package - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_package.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_package.yaml@CI-v0.17.0 with: operating_system: ${{ matrix.os }} python_version: ${{ matrix.python_version }} @@ -136,7 +136,7 @@ jobs: name: Create Binary - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_binary.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_binary.yaml@CI-v0.17.0 with: operating_system: ${{ matrix.os }} python_version: ${{ matrix.python_version }} @@ -159,7 +159,7 @@ jobs: name: Validate Binary - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_binary.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_binary.yaml@CI-v0.17.0 with: operating_system: ${{ matrix.os }} python_version: ${{ matrix.python_version }} @@ -173,7 +173,7 @@ jobs: name: Publish - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_publish_python.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_publish_python.yaml@CI-v0.17.0 with: release_sources_configuration_filename: .github/release_sources.yaml secrets: diff --git a/src/PythonProjectBootstrapper/ProjectGenerationUtils.py b/src/PythonProjectBootstrapper/ProjectGenerationUtils.py index a95a20a..dea7367 100644 --- a/src/PythonProjectBootstrapper/ProjectGenerationUtils.py +++ b/src/PythonProjectBootstrapper/ProjectGenerationUtils.py @@ -267,11 +267,16 @@ def CopyToOutputDir( merged_manifest[rel_filepath] = generated_hash # create and save manifest - yaml_comments = """##################################################################################### -# This file is used to determine whether changes have been made to any files in the project. -# These values are saved in case the project is regenerated so we can avoid overwriting any user changes. -# Please do not change the contents :) -#####################################################################################\n\n""" + yaml_comments = textwrap.dedent( + """\ + ############################################################################################################# + # This file is used by PythonProjectBootstrapper (https://github.com/gt-sse-center/PythonProjectBootstrapper) + # to determine whether changes have been made to any files in the project. These values are saved in case the + # project is regenerated so we can avoid overwriting any user changes. Please do not change the contents :) + ############################################################################################################# + + """, + ) if potential_manifest.is_file(): _ChangeManifestWritePermissions(manifest_filepath=potential_manifest, read_only=False) diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/workflows/standard.yaml b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/workflows/standard.yaml index 1ced8e9..1458fa6 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/workflows/standard.yaml +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/workflows/standard.yaml @@ -18,7 +18,7 @@ jobs: # ---------------------------------------------------------------------- action_contexts: name: "Display GitHub Action Contexts" - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_display_action_contexts.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_display_action_contexts.yaml@CI-v0.17.0 # ---------------------------------------------------------------------- validate: @@ -40,7 +40,7 @@ jobs: name: Validate - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python.yaml@CI-v0.17.0 with: operating_system: {% raw %}${{ matrix.os }}{% endraw %} python_version: {% raw %}${{ matrix.python_version }}{% endraw %} @@ -51,7 +51,7 @@ jobs: name: Postprocess Coverage Info - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_package_python_coverage.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_package_python_coverage.yaml@CI-v0.17.0 with: gist_id: {{ cookiecutter.gist_id }} gist_filename: {{ cookiecutter.github_project_name }}_coverage.json @@ -80,7 +80,7 @@ jobs: name: Create Package - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_package.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_package.yaml@CI-v0.17.0 with: operating_system: {% raw %}${{ matrix.os }}{% endraw %} python_version: {% raw %}${{ matrix.python_version }}{% endraw %} @@ -107,7 +107,7 @@ jobs: name: Validate Package - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_package.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_package.yaml@CI-v0.17.0 with: operating_system: {% raw %}${{ matrix.os }}{% endraw %} python_version: {% raw %}${{ matrix.python_version }}{% endraw %} @@ -131,7 +131,7 @@ jobs: name: Create Binary - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_binary.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_python_binary.yaml@CI-v0.17.0 with: operating_system: {% raw %}${{ matrix.os }}{% endraw %} python_version: {% raw %}${{ matrix.python_version }}{% endraw %} @@ -154,7 +154,7 @@ jobs: name: Validate Binary - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_binary.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_validate_python_binary.yaml@CI-v0.17.0 with: operating_system: {% raw %}${{ matrix.os }}{% endraw %} python_version: {% raw %}${{ matrix.python_version }}{% endraw %} @@ -178,7 +178,7 @@ jobs: name: Create Docker Image - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_docker_image.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_create_docker_image.yaml@CI-v0.17.0 with: operating_system: ubuntu-latest python_version: {% raw %}${{ matrix.python_version }}{% endraw %} @@ -200,7 +200,7 @@ jobs: name: Publish - uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_publish_python.yaml@CI-v0.15.6 + uses: davidbrownell/dbrownell_DevTools/.github/workflows/callable_publish_python.yaml@CI-v0.17.0 with: release_sources_configuration_filename: .github/release_sources.yaml secrets: diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md new file mode 100644 index 0000000..7c36b21 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +Feedback and contributions are very welcome! + +Here's help on how to make contributions, divided into the following sections: + +- [general information](#general-information), +- [vulnerability reporting](#vulnerability-reporting-security-issues), +- [code changes](#code-changes), + +## General information +For specific proposals, please provide them as [pull requests](https://github.com/coreinfrastructure/best-practices-badge/pulls) or [issues](https://github.com/coreinfrastructure/best-practices-badge/issues) via our [GitHub site]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}). + +The [DEVELOPMENT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) file explains how to install the program locally (highly recommended if you're going to make code changes). It also provides a quick start guide. + +### Pull requests and different branches recommended +Pull requests are preferred, since they are specific. For more about how to create a pull request, see https://help.github.com/articles/using-pull-requests/. + +We recommend creating different branches for different (logical) changes, and creating a pull request when you're done into the main branch. See the GitHub documentation on [creating branches](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) and [using pull requests](https://help.github.com/articles/using-pull-requests/). + +### How we handle proposals +We use GitHub to track proposed changes via its [issue tracker](https://github.com/coreinfrastructure/best-practices-badge/issues) and [pull requests](https://github.com/coreinfrastructure/best-practices-badge/pulls). Specific changes are proposed using those mechanisms. Issues are assigned to an individual, who works and then marks it complete. If there are questions or objections, the conversation are of that issue or pull request is used to resolve it. + +### We are proactive +In general we try to be proactive to detect and eliminate mistakes and vulnerabilities as soon as possible, and to reduce their impact when they do happen. We use a defensive design and coding style to reduce the likelihood of mistakes, a variety of tools that try to detect mistakes early, and an automatic test suite with significant coverage. We also release the software as open source software so others can review it. + +Since early detection and impact reduction can never be perfect, we also try to detect and repair problems during deployment as quickly as possible. This is especially true for security issues; see our [security information](#vulnerability-reporting-security-issues) for more. + +## Vulnerability reporting (security issues) +Please privately report vulnerabilities you find so we can fix them! + +See [SECURITY.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/SECURITY.md) for information on how to privately report vulnerabilities. + +## Code changes +To make changes to the "{{ cookiecutter.pypi_project_name }}" web application that implements the criteria, you may find [DEVELOPMENT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) helpful. + +The code should strive to be DRY (don't repeat yourself), clear, and obviously correct. Some technical debt is inevitable, just don't bankrupt us with it. Improved refactorizations are welcome. + +### Automated tests +When adding or changing functionality, please include new tests for them as part of your contribution. + +We require the code to have at a minimum statement coverage (that is measured and enforced during the [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) process); please ensure your contributions do not lower the coverage below that minimum. + +We encourage tests to be created first, run to ensure they fail, and then add code to implement the test (aka test driven development). However, each git commit should have both the test and improvement in the same commit, because 'git bisect' will then work well. + +### How to check proposed changes before submitting them +See [DEVELOPMENT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) for information on how to run tests on your local machine before submitting them as a pull request. + +### Git commit messages +When writing git commit messages, try to follow the guidelines in [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/): + +1. Separate subject from body with a blank line +2. Limit the subject line to 50 characters. (We're flexible on this, but do limit it to 72 characters or less.) +3. Capitalize the subject line +4. Do not end the subject line with a period +5. Use the imperative mood in the subject line (command form) +6. Wrap the body at 72 characters ("fmt -w 72") +7. Use the body to explain what and why vs. how (git tracks how it was changed in detail, don't repeat that) diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md index 1a95b46..ab0890d 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md @@ -12,7 +12,17 @@ {{ cookiecutter.project_description }} -### Overview + +## Contents +- [Overview](#overview) +- [Installation](#installation) +- [Contributing](#contributing) +- [Local Development](#local-development) +- [Vulnerability Reporting](#vulnerability-reporting-security-issues) +- [License](#license) + + +## Overview TODO: Complete this section @@ -20,25 +30,40 @@ TODO: Complete this section TODO: Complete this section -## Installation via Executable + +## Installation + +{{ cookiecutter.github_project_name }} can be installed via one of these methods: + +- [Installation via Executable](#installation-via-executable) +- [Installation via pip](#installation-via-pip) + +### Installation via Executable Download an executable for Linux, MacOS, or Windows to use the functionality provided by this repository without a dependency on [Python](https://www.python.org). 1. Download the archive for the latest release [here]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/releases/latest); the files will begin with `exe.` and contain the name of your operating system. 2. Decompress the archive -## Installation via pip +### Installation via pip Install the {{ cookiecutter.pypi_project_name }} package via [pip](https://pip.pypa.io/en/stable/) (Package Installer for Python) to use it with your python code. `pip install {{ cookiecutter.pypi_project_name }}` - +## Contributing +See [CONTRIBUTING.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/CONTRIBUTING.md) for information on contributing to {{ cookiecutter.github_project_name }}. + ## Local Development -Visit [DEVELOPMENT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) for information on developing or testing {{ cookiecutter.github_project_name }} on your local Linux, MacOS, or Windows machine. +See [DEVELOPMENT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) for information on developing or testing {{ cookiecutter.github_project_name }} on your local Linux, MacOS, or Windows machine. +## Vulnerability Reporting (Security Issues) +Please privately report vulnerabilities you find so we can fix them! + +See [SECURITY.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/SECURITY.md) for information on how to privately report vulnerabilities. + ## License {{ cookiecutter.github_project_name }} is licensed under the