From 59aaa4d51bfc6fac218bae33707764fd05c568cc Mon Sep 17 00:00:00 2001 From: soulless-viewer <29832584+soulless-viewer@users.noreply.github.com> Date: Sun, 11 Feb 2024 21:41:05 +0100 Subject: [PATCH 1/4] docs: add contribution rules --- .github/ISSUE_TEMPLATE/BUG_REPORT.md | 34 +++++++++++++ .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md | 33 +++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 23 +++++++++ CONTRIBUTING.md | 59 ++++++++++++++++++++++- 4 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/BUG_REPORT.md create mode 100644 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md new file mode 100644 index 0000000..620242b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -0,0 +1,34 @@ +--- +name: Bug report +about: Let us know what went wrong. +--- + +# Description + +Describe you situation in details (i.e. with the logs, screenshots, etc). \ +**Remember, it's better to add something extra than to miss something +important.** + +# Expected Behavior + +Describe the behavior you are expecting. + +# Current Behavior + +What is the current behavior? + +# Steps to Reproduce + +Provide detailed steps for reproducing the issue. + +1. Step 1 +2. Step 2 +3. ... + +# Context + +Provide any relevant info about your environment. + +* Tool Version: +* Operating System: +* Shell *(i.e. bash v4, zsh, etc.)* diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md new file mode 100644 index 0000000..34452a1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -0,0 +1,33 @@ +--- +name: Feature request +about: Let us know how we can make things better. +--- + +# Description + +Provide a detailed description of the feature you are requesting (e.g. text, +charts, diagrams, etc.) \ +**Remember, it's better to add something extra than to miss something +important.** + +# Use Case + +Describe a specific scenario or use case where this feature would be beneficial. \ +Explain why this feature is important for users or the project as a whole. + +# Proposed Implementation + +If you have any ideas or suggestions for how the feature could be implemented, +please outline them here. \ +Include any technical details or considerations that may be relevant. + +# Potential Impact + +Discuss the potential impact of implementing this feature as you see it. \ +Consider factors such as user experience, performance, scalability, etc. \ +Also, mention any potential risks or drawbacks associated with the feature. + +# Additional Information + +Include any additional information, resources, or references that may be +relevant to the feature request. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..af25951 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,23 @@ +## Description + +Describe your request in details. + +**Remember, it's better to add something extra than to miss something important.** + +## Checklist + +> [!TIP] +> *Remember, there is an option to create a **Draft Pull Request** if you are not ready for merging.* + +Check compliance with the following +[task list](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) +and describe any forced non-compliances: + +- [ ] [Consistency standards](https://github.com/GoogleCloudPlatform/gce-rescue/blob/main/CONTRIBUTING.md#consistency-standards) have been met +- [ ] New code complies with the [PEP8](https://peps.python.org/pep-0008/) +- [ ] All Python tests passed after the changes +- [ ] New changes have been tested on all supported platforms + +## Notes + +Any additional comments to make life easier for the reviewers? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d7656b..d0a3ac9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,4 +26,61 @@ information on using pull requests. ## Community Guidelines This project follows -[Google's Open Source Community Guidelines](https://opensource.google/conduct/). \ No newline at end of file +[Google's Open Source Community Guidelines](https://opensource.google/conduct/). + +## Consistency standards + +### Commit message + +We're trying to utilise the Conventional Commits specification. Try to follow +this unofficial agreement to enhance readability, clarity, and collaboration. + +https://www.conventionalcommits.org/en/v1.0.0/#specification + +### Branch name + +As well as with commit naming, there are a lot of ways to name a branches. +Let's try to follow these great guides to organise our project: + +- https://dev.to/couchcamote/git-branching-name-convention-cch +- https://dev.to/varbsan/a-simplified-convention-for-naming-branches-and-commits-in-git-il4 + +Branch name template: +``` + +``` + +- `category` distinguishes the types of activities in the branches. Options are: + - `feature` - for adding new features or refactoring existing code + - `bugfix` - for fixing an issue/bug (unplanned changes) + - `test` - for experimenting, PoC, etc. + +- `reference` points to the source of info about the purpose of this branch. + Current options are: + - `issue-123` - GitHub issue number + - `b-1234567` - Buganizer ID *(for now, only for Googlers)* + - `no-ref` - when there is no reference *(e.g. for `test` branches)* + +- `description-in-kebab-case` of the problem. Try to keep a balance between + brevity and informative. + +### Issue / Pull request content + +There are useful templates for a new issues and pull requests which will be +offered automatically. While you're not obligated to follow them, we recommend +that you do so in order to standardize the review process. + +### Code style + +We strive to use the standard [PEP8](https://peps.python.org/pep-0008/) document +for our code. You can utilize various tools to check syntax compliance, such as +[`pycodestyle`](https://pypi.org/project/pycodestyle/) *(former `pep8`)* or +[`black`](https://pypi.org/project/black/), as well as +[`pylint`](https://pypi.org/project/pylint/) with the standard configuration, +which can also be extremely useful *(sometimes too much)*. + +Despite being one of the most important yet ambiguous sections, the message is +as follows: + +**Try to be as simple as possible while balancing code readability and +efficiency.** From 23e7adfc47a9a82a0153fedf63fafa2283d0ca62 Mon Sep 17 00:00:00 2001 From: soulless-viewer <29832584+soulless-viewer@users.noreply.github.com> Date: Sun, 11 Feb 2024 21:48:01 +0100 Subject: [PATCH 2/4] docs: minor edit in PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index af25951..cd168cf 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,9 +9,7 @@ Describe your request in details. > [!TIP] > *Remember, there is an option to create a **Draft Pull Request** if you are not ready for merging.* -Check compliance with the following -[task list](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) -and describe any forced non-compliances: +Check compliance with the following [task list](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) and describe any forced non-compliances: - [ ] [Consistency standards](https://github.com/GoogleCloudPlatform/gce-rescue/blob/main/CONTRIBUTING.md#consistency-standards) have been met - [ ] New code complies with the [PEP8](https://peps.python.org/pep-0008/) From acf30636b9d9fdf9820403b8a0666e132bf76294 Mon Sep 17 00:00:00 2001 From: soulless-viewer <29832584+soulless-viewer@users.noreply.github.com> Date: Mon, 12 Feb 2024 10:32:46 +0100 Subject: [PATCH 3/4] docs: rewording the CONTRIBUTING.md --- CONTRIBUTING.md | 56 ++++++++++++++++++++++--------------------------- 1 file changed, 25 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0a3ac9..77f91b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,57 +30,51 @@ This project follows ## Consistency standards +> *Strive for simplicity while keeping a balance between code readability and +efficiency.* + ### Commit message -We're trying to utilise the Conventional Commits specification. Try to follow -this unofficial agreement to enhance readability, clarity, and collaboration. +We aim to adopt the Conventional Commits specification to improve readability, +clarity, and collaboration. https://www.conventionalcommits.org/en/v1.0.0/#specification ### Branch name -As well as with commit naming, there are a lot of ways to name a branches. -Let's try to follow these great guides to organise our project: - -- https://dev.to/couchcamote/git-branching-name-convention-cch -- https://dev.to/varbsan/a-simplified-convention-for-naming-branches-and-commits-in-git-il4 +Similar to commit naming, there are various methods to name branches. Let's +adhere to these simple template in our project: -Branch name template: ``` ``` -- `category` distinguishes the types of activities in the branches. Options are: - - `feature` - for adding new features or refactoring existing code - - `bugfix` - for fixing an issue/bug (unplanned changes) - - `test` - for experimenting, PoC, etc. +- **`category`** distinguishes the types of activities in the branches. Options +are: + - `feature` - adding a new feature or refactoring existing code + - `bugfix` - fixing an issue/bug (i.e. unplanned changes) + - `test` - experimenting, PoC, etc. -- `reference` points to the source of info about the purpose of this branch. - Current options are: +- **`reference`** points to the source of info about the purpose of this branch. +Current options are: - `issue-123` - GitHub issue number - `b-1234567` - Buganizer ID *(for now, only for Googlers)* - `no-ref` - when there is no reference *(e.g. for `test` branches)* -- `description-in-kebab-case` of the problem. Try to keep a balance between - brevity and informative. +- **`description-in-kebab-case`** of the problem. Try to keep a balance between + brevity and informativeness. ### Issue / Pull request content -There are useful templates for a new issues and pull requests which will be -offered automatically. While you're not obligated to follow them, we recommend -that you do so in order to standardize the review process. +Several useful templates for new issues and pull requests will be provided +automatically. Although not mandatory, adhering to them helps standardize the +review process. ### Code style -We strive to use the standard [PEP8](https://peps.python.org/pep-0008/) document -for our code. You can utilize various tools to check syntax compliance, such as -[`pycodestyle`](https://pypi.org/project/pycodestyle/) *(former `pep8`)* or -[`black`](https://pypi.org/project/black/), as well as -[`pylint`](https://pypi.org/project/pylint/) with the standard configuration, -which can also be extremely useful *(sometimes too much)*. - -Despite being one of the most important yet ambiguous sections, the message is -as follows: - -**Try to be as simple as possible while balancing code readability and -efficiency.** +We strive to adhere the standard [PEP8](https://peps.python.org/pep-0008/) +document for our code. Utilize tools like +[`pycodestyle`](https://pypi.org/project/pycodestyle/) *(formerly `pep8`)* or +[`black`](https://pypi.org/project/black/) for syntax compliance checks. +Additionally, consider [`pylint`](https://pypi.org/project/pylint/) with the +standard configuration for more comprehensive syntax analysis. From 268a728f17b8445f7f78250a8a2ea46c0bb37e8c Mon Sep 17 00:00:00 2001 From: soulless-viewer <29832584+soulless-viewer@users.noreply.github.com> Date: Tue, 13 Feb 2024 12:54:51 +0100 Subject: [PATCH 4/4] docs: adding the default base branch paragraph --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77f91b7..48bc6a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,10 @@ Several useful templates for new issues and pull requests will be provided automatically. Although not mandatory, adhering to them helps standardize the review process. +All Pull Requests, with rare exceptions *(such as docs, minor wording edits, +etc.), should use the `develop` branch as a base. Only team members have +permissions to push to the `main` branch. + ### Code style We strive to adhere the standard [PEP8](https://peps.python.org/pep-0008/)