diff --git a/.gitignore b/.gitignore index 7768bca..a832b25 100644 --- a/.gitignore +++ b/.gitignore @@ -13,5 +13,5 @@ build/** dist/** src/PythonProjectBootstrapper.egg-info/** -key.pri -key.pub +minisign_key.pri +minisign_key.pub diff --git a/README.md b/README.md index a84dfc1..48bc17d 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,9 @@ Tool that helps in the creation of python projects. - Wheel deployment to [PyPi](https://pypi.org) - Executable generation via [cx_Freeze](https://marcelotduarte.github.io/cx_Freeze/) - Full [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration), [Continuous Delivery](https://en.wikipedia.org/wiki/Continuous_delivery), and [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) (via [GitHub Actions](https://github.com/features/actions)) for everything listed above +- GitHub [Recommended Community Standards](https://opensource.guide/) documentation +- GitHub [pull request template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) +- GitHub [issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) - [Optional] Build artifact signing via [Minisign](https://jedisct1.github.io/minisign/) - [Optional] Participation in the [Open Source Security Foundation (OpenSSF) Best Practices Badge Program](https://www.bestpractices.dev/) - [Optional] Generation of development environment [docker](https://www.docker.com/) [images](https://aws.amazon.com/compare/the-difference-between-docker-images-and-containers/) in support of [FAIR principles](https://www.go-fair.org/fair-principles/) @@ -161,6 +164,7 @@ There are other tools available that offer similar functionality, each emphasizi | [LINCC Frameworks Python Project Template](https://github.com/lincc-frameworks/python-project-template) | This project template codifies LINCC-Framework's best practices for python code organization, testing, documentation, and automation. | | [Cookiecutter Django](https://github.com/cookiecutter/cookiecutter-django) | Cookiecutter Django is a framework for jumpstarting production-ready Django projects quickly. | | [cookiecutter-pylibrary](https://github.com/ionelmc/cookiecutter-pylibrary) | Enhanced cookiecutter template for Python libraries. | +| [repo-scaffolder](https://github.com/DSACMS/repo-scaffolder) | Templates and commandline tools for creating repositories for US Federal open source projects | ### Templating Systems diff --git a/src/PythonProjectBootstrapper/ProjectGenerationUtils.py b/src/PythonProjectBootstrapper/ProjectGenerationUtils.py index 4067e1d..7c3f424 100644 --- a/src/PythonProjectBootstrapper/ProjectGenerationUtils.py +++ b/src/PythonProjectBootstrapper/ProjectGenerationUtils.py @@ -267,7 +267,7 @@ def CopyToOutputDir( and current_file_hash == existing_manifest[rel_filepath] ): modified_template_files.append(output_dir_filepath.as_posix()) - elif potential_manifest.is_file(): + elif rel_filepath in existing_manifest: # If here, the file no longer exists. We still want the file to exist in the manifest # (so that future generations are still aware of it), but do not want it to be created # again. diff --git a/src/PythonProjectBootstrapper/package/cookiecutter.json b/src/PythonProjectBootstrapper/package/cookiecutter.json index 3c76ff6..59f20db 100644 --- a/src/PythonProjectBootstrapper/package/cookiecutter.json +++ b/src/PythonProjectBootstrapper/package/cookiecutter.json @@ -40,7 +40,7 @@ "pypi_project_name": "\n\nPlease enter the name of your project as it will appear on PyPI (https://pypi.org). This name cannot be associated with any other project on PyPI.\n\n", "gist_id": "\n\nPlease enter the GitHub gist id for use with this project.\n\nGitHub defines a gist as \"a simple way to share snippets and pastes with others.\" The generated python project will use a gist to store information dynamically generated during the build (for example code coverage information) that can be retrieved at a later time (for example, to display a code coverage badge in the project's README.md file). To create a gist:\n 1. Go to https://gist.github.com/\n 2. Enter the following values in their respective fields:\n\n Gist description...: Gist used by GitHub Action workflows to store and retrieve dynamic information (oftentimes used to create and display badges).\n Filename including extension...: README.md\n File contents: Gist used by GitHub Action workflows to store and retrieve dynamic information (oftentimes used to create and display badges).\n\n 3. Click the \"Create secret gist\" button\n 4. Copy the gist id (this will be the hex string at the end of the url associated with the gist\n that was just created). It will look something like:\n\n https://gist.github.com//4c10281ff1abc26cafcb9a5f9a8a443e\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n This is the gist id\n\n", "gist_username": "\n\nPlease enter the username associated with your gist_id. In most cases, this will be the same as your GitHub username.\n\n", - "minisign_public_key": "\n\nPlease enter your Minisign public key for use with this project or \"none\" if you do not want to sign binaries (this is not recommended).\n\nMinisign is a dead simple tool to sign files and verify signatures. It is a secure tool that uses the Ed25519 public-key signature system. More information is available at https://jedisct1.github.io/minisign/.\n\nNote that these steps rely on docker (docker.com), so please make sure that docker is installed and working properly on your machine.\nAdditional information is available at https://docs.docker.com/engine/install/.\n\nTo create a Minisign key pair for use with this project:\n 1. Run 'docker run -i --rm -v \".:/host\" jedisct1/minisign -G -p /host/key.pub -s /host/key.pri -W'\n 2. Ensure that the file 'key.pri' exists (this file will be used later).\n 3. Open the file 'key.pub' and copy the key from the file; the key will be the last line of the file.\n 4. Paste the copied key here.\n\n", + "minisign_public_key": "\n\nPlease enter your Minisign public key for use with this project or \"none\" if you do not want to sign binaries (this is not recommended).\n\nMinisign is a dead simple tool to sign files and verify signatures. It is a secure tool that uses the Ed25519 public-key signature system. More information is available at https://jedisct1.github.io/minisign/.\n\nNote that these steps rely on docker (docker.com), so please make sure that docker is installed and working properly on your machine.\nAdditional information is available at https://docs.docker.com/engine/install/.\n\nTo create a Minisign key pair for use with this project:\n 1. Run 'docker run -i --rm -v \".:/host\" jedisct1/minisign -G -p /host/minisign_key.pub -s /host/minisign_key.pri -W'\n 2. Ensure that the file 'minisign_key.pri' exists (this file will be used later).\n 3. Open the file 'minisign_key.pub' and copy the key from the file; the key will be the last line of the file.\n 4. Paste the copied key here.\n\n", "openssf_best_practices_badge_id": "\n\nPlease enter your OpenSSF Best Practices Badge id for use with this project or \"none\" if you do not want to display this badge. Visit https://www.bestpractices.dev/ for additional information about this badge.\n\nTo create a OpenSSF Best Practices Badge id for use with this project:\n 1. Visit https://www.bestpractices.dev/\n 2. Click the \"Get Your Badge Now!\" button.\n 3. In the top form, select the corresponding repository.\n 4. Click the \"Submit GitHub Repository\" button.\n 5. Copy the badge id from the URL of the page that is displayed. It will look something like:\n\n https://www.bestpractices.dev/en/projects/12345\n ^^^^^\n This is the badge id\n\n", "create_docker_image": "\n\nWould you like the GitHub Action workflows to create docker images of the development environment? These images can be used to produce exact results across different commits made to the repository over time (which is especially valuable when writing scientific software).\n\n" }, diff --git a/src/PythonProjectBootstrapper/package/cookiecutter_prompts.yaml b/src/PythonProjectBootstrapper/package/cookiecutter_prompts.yaml index 4a45ba5..dd3c0c5 100644 --- a/src/PythonProjectBootstrapper/package/cookiecutter_prompts.yaml +++ b/src/PythonProjectBootstrapper/package/cookiecutter_prompts.yaml @@ -87,9 +87,9 @@ minisign_public_key: |- Additional information is available at https://docs.docker.com/engine/install/. To create a Minisign key pair for use with this project: - 1. Run 'docker run -i --rm -v ".:/host" jedisct1/minisign -G -p /host/key.pub -s /host/key.pri -W' - 2. Ensure that the file 'key.pri' exists (this file will be used later). - 3. Open the file 'key.pub' and copy the key from the file; the key will be the last line of the file. + 1. Run 'docker run -i --rm -v ".:/host" jedisct1/minisign -G -p /host/minisign_key.pub -s /host/minisign_key.pri -W' + 2. Ensure that the file 'minisign_key.pri' exists (this file will be used later). + 3. Open the file 'minisign_key.pub' and copy the key from the file; the key will be the last line of the file. 4. Paste the copied key here. openssf_best_practices_badge_id: |- diff --git a/src/PythonProjectBootstrapper/package/hooks/post_gen_project.py b/src/PythonProjectBootstrapper/package/hooks/post_gen_project.py index f7a1935..18d01ba 100644 --- a/src/PythonProjectBootstrapper/package/hooks/post_gen_project.py +++ b/src/PythonProjectBootstrapper/package/hooks/post_gen_project.py @@ -106,16 +106,16 @@ def SavePrompts() -> None: f"""\ In this step, we will save the Minisign private key as a GitHub Action Secret. - 1. Open 'key.pri' in a text editor. + 1. Open 'minisign_key.pri' in a text editor. 2. Copy the contents of the file. 3. Visit {{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/settings/secrets/actions 4. In the "Repository secrets" section... 5. Click the "New repository secret" button 6. Enter the values: Name: MINISIGN_PRIVATE_KEY - Secret: + Secret: 7. Click the "Save" button - 8. Save 'key.pri' in a safe place. + 8. Save 'minisign_key.pri' in a safe place. """, ) {% endif %} @@ -315,15 +315,15 @@ def SavePrompts() -> None: {% endif %} - prompts["Update README.md"] = textwrap.dedent( - """\ - In this step, we will update the README.md file with information about your project. + for filename in ["README.md", "MAINTAINERS.md"]: + prompts[f"Update {filename}"] = textwrap.dedent( + f"""\ + In this step, we will update the {filename} file with information about your project. - 1. Edit README.md - 2. Replace the "TODO" comment in the "Overview" section. - 3. Replace the "TODO" comment in the "How to use {{ cookiecutter.github_project_name }}" section. - """, - ) + 1. Edit {filename} + 2. Replace the "TODO" comments in the file. + """, + ) with open(prompt_filename, "w") as prompt_file: # Modify the keys to include an index to ensure that the prompts are displayed in the diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/CODEOWNERS b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/CODEOWNERS new file mode 100644 index 0000000..8f034bc --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/CODEOWNERS @@ -0,0 +1 @@ +* @{{cookiecutter.github_username}} diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/bug_report.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..49fc153 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,32 @@ +--- +name: Bug report +about: Create a report to help us improve. +title: '' +labels: '' +assignees: '' + +--- + +## Describe the bug +A clear and concise description of what the bug is. + +## To Reproduce +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +## Expected behavior +A clear and concise description of what you expected to happen. + +## Screenshots +If applicable, add screenshots to help explain your problem. + +## Environment (please complete the following information): + - OS: [e.g. iOS] + - Python Version: [e.g. 3.12, 3.11, etc.] + - {{ cookiecutter.pypi_project_name }} Version [e.g. 1.2.3] + +## Additional context +Add any other context about the problem here. diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/config.yml b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ac2e8b4 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/custom.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/custom.md new file mode 100644 index 0000000..a8cf75b --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/custom.md @@ -0,0 +1,8 @@ +--- +name: Custom issue template +about: Create an issue that isn't a bug or feature request. +title: '' +labels: '' +assignees: '' + +--- diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/feature_request.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..dbf4454 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this {{ cookiecutter.github_project_name }}. +title: '' +labels: '' +assignees: '' + +--- + +## Is your feature request related to a problem? Please describe. +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +## Describe the solution you'd like +A clear and concise description of what you want to happen. + +## Describe alternatives you've considered +A clear and concise description of any alternative solutions or features you've considered. + +## Additional context +Add any other context or screenshots about the feature request here. diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/pull_request_template.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/pull_request_template.md new file mode 100644 index 0000000..f26ff1f --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.github/pull_request_template.md @@ -0,0 +1,8 @@ +## :pencil: Description +Please include a summary of the change and the work item associated with it. + +## :gear: Work Item +Please include link to the corresponding GitHub Issue or Project work item. + +## :movie_camera: Demo +Please provide any images, GIFs, or videos that show the effect of your changes (if applicable). A picture is worth a thousand words. diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.gitignore b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.gitignore index 6fa487d..556f614 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.gitignore +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/.gitignore @@ -13,5 +13,5 @@ build/** dist/** src/{{ cookiecutter.pypi_project_name }}.egg-info/** -key.pri -key.pub +minisign_key.pri +minisign_key.pub diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CODE_OF_CONDUCT.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8274985 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CODE_OF_CONDUCT.md @@ -0,0 +1,25 @@ +# {{ cookiecutter.github_project_name }} Open Source Code of Conduct + +## Principles +These principles guide our data, product, and process decisions, architecture, and approach. + +- Open means transparent and participatory. +- We take a modular and modern approach to software development. +- We build open-source software and open-source process. +- We value ease of implementation. +- Fostering community includes building capacity and making our software and processes accessible to participants with diverse backgrounds and skillsets. +- Data (and data science) is as important as software and process. We build open data sets where possible. +- We strive for transparency for algorithms and places we might be introducing bias. + +## Community Guidelines +Information on contributing to this repository is available in our [Contributing file](CONTRIBUTING.md). + +When participating in {{ cookiecutter.github_project_name }} open source community conversations and spaces, we ask individuals to follow the following guidelines: + +- Embrace a culture of learning, and educate each other. We are all entering this conversation from different starting points and with different backgrounds. There are no dumb questions. +- Take space and give space. We strive to create an equitable environment in which all are welcome and able to participate. We hope individuals feel comfortable voicing their opinions and providing contributions and will do our best to recognize and make space for individuals who may be struggling to find space here. Likewise, we expect individuals to recognize when they are taking up significant space and take a step back to allow room for others. +- Be respectful. +- Default to positive. Assume others' contributions are legitimate and valuable and that they are made with good intention. + +## Acknowledgements +This Community Guidelines was adapted from the [United States Digital Service](https://usds.gov) [Justice40](https://thejustice40.com) open source [repository](https://github.com/usds/justice40-tool). diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md index 7c36b21..5110d1d 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/CONTRIBUTING.md @@ -1,58 +1,39 @@ -# Contributing +# Contribution Guidelines -Feedback and contributions are very welcome! +## Contributor Code of Conduct +As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. -Here's help on how to make contributions, divided into the following sections: +We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity, expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. -- [general information](#general-information), -- [vulnerability reporting](#vulnerability-reporting-security-issues), -- [code changes](#code-changes), +Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct. + +[Project maintainers](MAINTAINERS.md) have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the [project maintainers](MAINTAINERS.md). ## 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. +The [DEVELOPMENT.md](DEVELOPMENT.md) file explains how to install the program locally (highly recommended if you're going to make code changes). It also provides information useful for making changes and validating them locally before submitting a pull request. ### 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/). +We recommend creating different branches for different (logical) changes, and creating a pull request into the `main` branch when you're done. 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 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 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. +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 information. ## 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. +See [SECURITY.md](SECURITY.md) for information on how to privately report vulnerabilities. -### 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/): +## Acknowledgements -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) +This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/) diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/DEVELOPMENT.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/DEVELOPMENT.md index bace98c..64bb4a1 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/DEVELOPMENT.md +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/DEVELOPMENT.md @@ -1,34 +1,28 @@ -## Local Development +# Local Development -Follow these steps to prepare the repository for local development activities. +## Enlistment +Enlistment in this repository involves these steps. -1) Clone this repository -2) Bootstrap the local repository by running... - | Operating System | Command | - | --- | --- | - | Linux / MacOS |

Standard:
`Bootstrap.sh`

Standard + packaging:
`Bootstrap.sh --package`

| - | Windows |

Standard:
`Bootstrap.cmd`

Standard + packaging:
`Bootstrap.cmd --package`

| -3) Activate the development environment by running... - | Operating System | Command | - | --- | --- | - | Linux / MacOS | `. ./Activate.sh` | - | Windows | `Activate.cmd` | -4) Invoke `Build.py` - | Command | Description | Example | Notes | - | --- | --- | --- | --- | - | `black` | Validates that the source code is formatted by [black](https://github.com/psf/black). |

Validation:
`python Build.py black`

Perform formatting:
`python Build.py black --format`

| | - | `pylint` | Validates the source code using [pylint](https://github.com/pylint-dev/pylint). | `python Build.py pylint` | | - | `pytest` | Runs automated tests using [pytest](https://docs.pytest.org/). |

Without Code Coverage:
`python Build.py pytest`

With Code Coverage:
`python Build.py pytest --code-coverage`

| | - | `update_version` | Updates the [semantic version](https://semver.org/) of the package based on git commits using [AutoGitSemVer](https://github.com/davidbrownell/AutoGitSemVer). | `python Build.py update_version` | | - | `package` | Creates a Python wheel package for distribution; outputs to the `/dist` directory. | `python Build.py package` | Requires `--package` when bootstrapping in step #2. | - | `publish` | Publishes a Python wheel package to [PyPi](https://pypi.org/). |

https://test.pypi.org:
`python Build.py publish`

https://pypi.org:
`python Build.py publish --production`

| Requires `--package` when bootstrapping in step #2. | - | `build_binary` | Builds an executable for your package that can be run on machines without a python installation; outputs to the `/build` directory. | `python Build.py build_binary` | Requires `--package` when bootstrapping in step #2. | +| Step | Command Line | Description | +| --- | --- | --- | +| 1. Clone the repository locally | `git clone {{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}` | https://git-scm.com/docs/git-clone | +| 2. Bootstrap the repository |
Linux / MacOS:./Bootstrap.sh [--python-version <python version>] [--package]
Windows:Bootstrap.cmd [--python-version <python version>] [--package]
|

Prepares the repository for local development by enlisting in all dependencies.

The `--package` argument is required to run the [Python Package Creation](#python-package-creation) and [Python Package Publising](#python-package-publishing) steps below. | +| 3. Activate the environment |
Linux / MacOS:. ./Activate.sh
Windows:Activate.cmd
|

Activates the terminal for development. Each new terminal window must be activated.

`Activate.sh/.cmd` is actually a shortcut to the most recently bootstrapped version of python (e.g. `Activate3.11.sh/.cmd`). With this functionality, it is possible to support multiple python versions in the same repository and activate each in a terminal using the python-specific activation script.

| +| 4. [Optional] Deactivate the environment |
Linux / MacOS:. ./Deactivate.sh
Windows:Deactivate.cmd
| Deactivates the terminal environment. Deactivating is optional, as the terminal window itself may be closed when development activities are complete. | + +## Development Activities + +Each of these activities can be invoked from an activated terminal on your local machine. + +| Activity | Command Line | Description | Invoked by [Continuous Integration]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/.github/workflows/standard.yaml) | +| --- | --- | --- | :---: | +| Code Formatting | `python Build.py black [--format]` | Format source code using [black](https://github.com/psf/black) based on settings in [pyproject.toml]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/pyproject.toml). | :white_check_mark: | +| Static Code Analysis | `python Build pylint` | Validate source code using [pylint](https://github.com/pylint-dev/pylint) based on settings in [pyproject.toml]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/pyproject.toml). | :white_check_mark: | +| Automated Testing | `python Build pytest [--code-coverage]` | Run automated tests using [pytest](https://docs.pytest.org/) and (optionally) extract code coverage information using [coverage](https://coverage.readthedocs.io/) based on settings in [pyproject.toml]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/pyproject.toml). | :white_check_mark: | +| Semantic Version Generation | `python Build.py update_version` | Generate a new [Semantic Version](https://semver.org) based on git commits using [AutoGitSemVer](https://github.com/davidbrownell/AutoGitSemVer). Version information is stored [here]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/src/{{ cookiecutter.pypi_project_name }}/__init__.py). | :white_check_mark: | +| Python Package Creation |

`python Build.py package`

Requires that the repository was bootstrapped with the `--package` flag.

| Create a python package using [setuptools](https://github.com/pypa/setuptools) based on settings in [pyproject.toml]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/pyproject.toml). |

:white_check_mark:

Packages are built for all supported python versions.

| +| Python Package Publishing |

`python Build.py publish`

Requires that the repository was bootstrapped with the `--package` flag.

| Publish a python package to [PyPi](https://pypi.org). | :white_check_mark: | +| Build Binaries | `python Build.py build_binaries` | Create a python binary for your current operating system using [cx_Freeze](https://cx-freeze.readthedocs.io/) based on settings in [BuildBinary.py]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/src/BuildBinary.py). |

:white_check_mark:

Binaries are built for Linux, MacOS, and Windows.

{%- if cookiecutter.create_docker_image %} - | `create_docker_image` | Creates a [Docker](https://www.docker.com/) image based on the current development environment. This supports the "Reusable" aspect of [FAIR principles](https://www.go-fair.org/fair-principles/) by creating a snapshot of the repository and all of its dependencies as they exist in a single moment in time. | `python Build.py create_docker_image` | Requires docker. | +| Development Docker Image | `python Build.py create_docker_image` | Create a [docker](https://docker.com) image for a bootstrapped development environment. This functionality is useful when adhering to the [FAIR principles for research software](https://doi.org/10.1038/s41597-022-01710-x) by supporting the creation of a development environment and its dependencies as they existed at the moment when the image was created. | :white_check_mark: | {% endif %} - -5) [Optional] Deactivate the development environment by running... - | Operating System | Command | - | --- | --- | - | Linux / MacOS | `. ./Deactivate.sh` | - | Windows | `Deactivate.cmd` | diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/GOVERNANCE.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/GOVERNANCE.md new file mode 100644 index 0000000..9256d60 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/GOVERNANCE.md @@ -0,0 +1,2 @@ +# Governance +This project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contribution Guidelines](CONTRIBUTING.md). diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/MAINTAINERS.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/MAINTAINERS.md new file mode 100644 index 0000000..9a8d022 --- /dev/null +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/MAINTAINERS.md @@ -0,0 +1,14 @@ +# Maintainers + +This page lists all active maintainers of this repository. If you were a maintainer and would like to add your name to the Emeritus list, please send us a pull request. + +See [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing](CONTRIBUTING.md) for general contribution guidelines. + +## Current Maintainers +| Maintainer | GitHub ID | Affiliation | +| --- | --- | --- | +TODO: Add maintainers + +## Emeritus +| Maintainer | GitHub ID | Affiliation | +| --- | --- | --- | diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md index 23ae560..1710114 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/README.md @@ -19,9 +19,8 @@ ## Contents - [Overview](#overview) - [Installation](#installation) -- [Contributing](#contributing) -- [Local Development](#local-development) -- [Vulnerability Reporting](#vulnerability-reporting-security-issues) +- [Development](#development) +- [Additional Information](#additional-information) - [License](#license) @@ -69,18 +68,24 @@ Install the {{ cookiecutter.pypi_project_name }} package via [pip](https://pip.p `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 }}. +## Development -## Local Development +Please visit [Contributing]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/CONTRIBUTING.md) and [Development]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) for information on contributing to this project. -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! +## Additional Information -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. +Additional information can be found at these locations. + +| Title | Document | Description | +| --- | --- | --- | +| Code of Conduct | [CODE_OF_CONDUCT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/CODE_OF_CONDUCT.md) | Information about the the norms, rules, and responsibilities we adhere to when participating in this open source community. | +| Contributing | [CONTRIBUTING.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/CONTRIBUTING.md) | Information about contributing code changes to this project. | +| Development | [DEVELOPMENT.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/DEVELOPMENT.md) | Information about development activities involved in making changes to this project. | +| Governance | [GOVERNANCE.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/GOVERNANCE.md) | Information about how this project is governed. | +| Maintainers | [MAINTAINERS.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/MAINTAINERS.md) | Information about individuals who maintain this project. | +| Security | [SECURITY.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/SECURITY.md) | Information about how to privately report security issues associated with this project. | ## License diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/SECURITY.md b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/SECURITY.md index cfc3942..646a7af 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/SECURITY.md +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/SECURITY.md @@ -2,8 +2,8 @@ If you find a significant vulnerability, or evidence of one, please report it privately. -We prefer that you use the [GitHub mechanism for privately reporting a vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability). Under the [main repository's security tab]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/security), in the left sidebar, under "Reporting", click Advisories, then click "Report a vulnerability" to open the advisory form. +We prefer that you use the [GitHub mechanism for privately reporting a vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability). Under the [main repository's security tab]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/security), in the left sidebar, under "Reporting", click "Advisories", click the "New draft security advisory" button to open the advisory form. We will gladly give credit to anyone who reports a vulnerability so that we can fix it. If you want to remain anonymous or pseudonymous instead, please let us know that; we will gladly respect your wishes. -We gladly welcome patches to fix such vulnerabilities! See [CONTRIBUTING.md]({{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/blob/main/CONTRIBUTING.md) for information about contributions. +We gladly welcome patches to fix such vulnerabilities! See [CONTRIBUTING.md](CONTRIBUTING.md) for information about contributions. diff --git a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/src/{{ cookiecutter.pypi_project_name }}/__init__.py b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/src/{{ cookiecutter.pypi_project_name }}/__init__.py index 319caa1..22cedce 100644 --- a/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/src/{{ cookiecutter.pypi_project_name }}/__init__.py +++ b/src/PythonProjectBootstrapper/package/{{ cookiecutter.__empty_dir }}/src/{{ cookiecutter.pypi_project_name }}/__init__.py @@ -3,7 +3,7 @@ # Note that this value will be overwritten by calls to `python ../../Build.py update_version` based # on changes observed in the git repository. The default value below will be used until the value -# here is explicitly updated by the Continuous Integration system as part of a commit. +# here is explicitly updated by the Continuous Integration system. __version__ = "0.1.0" from .Math import Add, Sub, Mult, Div