Skip to content

Commit

Permalink
Updating CONTRIBUTING.md (#6)
Browse files Browse the repository at this point in the history 
feat: Updating CONTRIBUTING.md to reflect project requirements.
  • Loading branch information
@drduhe
drduhe authored Sep 19, 2023
1 parent cf30ce5 commit 8ce7dd5
Show file tree
Hide file tree
Showing 4 changed files with 243 additions and 67 deletions.
275 changes: 238 additions & 37 deletions CONTRIBUTING.md
100644 → 100755
View file
Original file line number Diff line number Diff line change
@@ -1,59 +1,260 @@
# Contributing Guidelines
# OSML Contributing Guidelines

Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
documentation, we greatly value feedback and contributions from our community.
Thank you for your interest in contributing to our project! This document will guide you through the process of
contributing to our repository using a release-based GitFlow workflow. Please read the guidelines carefully in order to
submit your pull requests effectively.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.
## Table of Contents

- [Release-based GitFlow](#release-based-gitflow)
- [Branches](#branches)
- [Linting](#linting)
- [Use Cases](#use-cases)
- [Develop a new feature](#develop-a-new-feature)
- [Develop multiple features in parallel](#develop-multiple-features-in-parallel)
- [Create and deploy a release](#create-and-deploy-a-release)
- [Production hot fix](#production-hot-fix)
- [Code Style](#code-style)
- [Commit Messages](#commit-messages)
- [Issue Tracking](#issue-tracking)

## Reporting Bugs/Feature Requests
## Release-based GitFlow

We welcome you to use the GitHub issue tracker to report bugs or suggest features.
We follow a release-based GitFlow branching model to manage our codebase. It involves different types of branches to
ensure proper version control and collaboration. The primary branches in this workflow are:

When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
note- `main`: This branch represents the latest production-ready state of the project code.
- `dev`: This branch is used as the integration branch, combining all feature branches for a specific release.
- `release/vX.Y.Z`: Branches in the format of `release/vX.Y.Z` are used to prepare a specific release.
- `feature/*`: Feature branches are created for the development of new features or significant enhancements.
- `hotfix/*`: Hotfix branches are created for bug fixes against production code.

* A reproducible test case or series of steps
* The version of our code being used
* Any modifications you've made relevant to the bug
* Anything unusual about your environment or deployment

## Branches

## Contributing via Pull Requests
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
Here's a brief description of the supported branches in our repository:

1. You are working against the latest source on the *main* branch.
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
![Release Deployment workflow](images/release-deployment.png)

To send us a pull request, please:
| Branch | Protected? | Base Branch | Description |
|:-----------------|:-----------|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `main` | YES | N/A | What is live in production (**stable**).<br/>A pull request is required to merge code into `main`. |
| `dev` | YES | `main` | The latest state of development (**unstable**).<br/>A pull request is required to merge code into `dev` |
| `feature/*` | NO | `dev` | Cutting-edge features (**unstable**). These branches are used for any maintenance features / active development. |
| `release/vX.Y.Z` | NO | `dev` | A temporary release branch that follows the [semver](http://semver.org/) versioning. This is what is sent to UAT.<br/>A pull request is required to merge code into any `release/vX.Y.Z` branch. |
| `hotfix/*` | NO | `main` | These are bug fixes against production.<br/>This is used because develop might have moved on from the last published state.<br/>Remember to merge this back into develop and any release branches. |

1. Fork the repository.
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
3. Ensure local tests pass.
4. Commit to your fork using clear commit messages.
5. Send us a pull request, answering any default questions in the pull request interface.
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
## Linting

This package uses a number of tools to enforce formatting, linting, and general best practices:
* [eslint](https://github.com/pre-commit/mirrors-eslint) to check pep8 compliance and logical errors in code
* [prettier](https://github.com/pre-commit/mirrors-prettier) to check pep8 compliance and logical errors in code
* [pre-commit](https://github.com/pre-commit/pre-commit-hooks) to install and control linters in githooks

## Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
After pulling the repository, you should enable auto linting git commit hooks by running:

```bash
python3 -m pip install pre-commit
pre-commit install
```

## Code of Conduct
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
[email protected] with any additional questions or comments.
In addition to running the linters against files included in a commit, you can perform linting on all the files
in the package by running:
```bash
pre-commit run --all-files --show-diff-on-failure
```
or if using tox
```bash
tox -e lint
````

## Use Cases

## Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
### Develop a new feature

1. Make sure your `dev` branch is up-to-date

## Licensing
2. Create a feature branch based off of `dev`

See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
```bash
$ git checkout dev
$ git checkout -b feature/new-documentation
$ git push --set-upstream feature/new-documentation
```

3. Develop the code for the new feature and commit. Push your changes often. This
allows others to see your changes and suggest improvements/changes as well as
provides a safety net should your hard drive crash.

```bash
$ ... make changes
$ git add -A .
$ git commit -m "Add new documentation files"
$ ... make more changes
$ git add -A .
$ git commit -m "Fix some spelling errors"
$ git push
```

4. Navigate to the project on [GitHub](https://github.com) and open a pull request with
the following branch settings:
* Base: `dev`
* Compare: `feature/new-documentation`

5. When the pull request was reviewed, merge and close it and delete the
`feature/new-documentation` branch.

### Develop multiple features in parallel

There's nothing special about that. Each developer follows the above [Develop a new feature](#develop-a-new-feature) process.
### Create and deploy a release
1. Merge `main` into `dev` to ensure the new release will contain the
latest production code. This reduces the chance of a merge conflict during
the release.
```bash
$ git checkout dev
$ git merge main
```
2. Create a new `release/vX.Y.Z` release branch off of `dev`.
```bash
$ git checkout -b release/vX.Y.Z
$ git push --set-upstream release/vX.Y.Z
```
3. Stabilize the release by using bugfix branches off of the `release/vX.Y.Z` branch
(the same way you would do a feature branch off of `dev`).
```bash
$ git checkout release/vX.Y.Z
$ git checkout -b hotfix/fix-label-alignment
$ git push --set-upstream hotfix/fix-label-alignment
... do work
$ git commit -m "Adjust label to align with button"
$ git push
```
4. When the code is ready to release, navigate to the project on
[GitHub](https://github.com) and open a pull request with the following branch
settings:
* Base: `main`
* Compare: `release/vX.Y.Z`
Paste the Release Checklist into the PR body. Each project should define a release
checklist. TBD - will link release checklist here.
5. At some point in the checklist you will merge the release branch into `main`.
You can do this by using the "Merge pull request" button on the release PR.
6. Now you are ready to create the actual release. Navigate to the project page
on GitHub and draft a new release with the following settings:
* Tag version: `vX.Y.Z`
* Target: `main`
* Release title: `Release vX.Y.Z`
* Description: Includes a high-level list of things changed in this release.
Click `Publish release`.
7. Merge the `release/vX.Y.Z` into `dev`.
```bash
$ git checkout dev
$ git merge release/vX.Y.Z
$ git push
```
8. Finish off the tasks in the release checklist. Once everything is done, close
the release PR.
9. Delete the release branch on GitHub.
### Production hot fix
A production hotfix is very similar to a full-scale release except that you do
your work in a branch taken directly off of `main`. Hotfixes are useful in cases
where you want to patch a bug in a released version, but `dev` has unreleased
code in it already.
**TBD: Insert diagram**
1. Create a hot fix branch based off of `main`.
```bash
$ git checkout main
$ git checkout -b hotfix/documentation-broken-links
$ git push --set-upstream origin hotfix/documentation-broken-links
```
2. Add a test case to validate the bug, fix the bug, and commit.
```bash
... add test, fix bug, verify
$ git add -A .
$ git commit -m "Fix broken links"
$ git push
```
3. Navigate to the project on [GitHub](https://github.com) and open a pull request
with the following branch settings:
* Base: `main`
* Compare: `hotfix/documentation-broken-links`
Paste your release checklist into the PR and work through the PR to get the
hotfix into production.
4. At some point in the checklist you will merge the hotfix branch into `main`.
You can do this by using the "Merge pull request" button on the release PR.
5. Now that the hotfix code is in `main` you are ready to create the actual
release. Navigate to the project page on GitHub and draft a new release with
the following settings:
* Tag version: `vX.Y.Z`
* Target: `main`
* Release title: `Release vX.Y.Z (hotfix)`
* Description: Includes a high-level list of things changed in this release.
Click `Publish release`.
*Note: Hotfix releases _are_ actual releases. You should bump at least the
patch part of the version when releasing a hotfix, and so even hotfixes go
through the process of creating a release like this.*
1. Merge the `hotfix/documentation-broken-links` into `dev`.
```bash
$ git checkout dev
$ git merge hotfix/documentation-broken-links
$ git push
```
2. Finish off the tasks in the release checklist. Once everything is done, close
the hotfix PR.
## Code Style
We maintain a consistent code style throughout the project, so please ensure your changes align with our existing style.
Take a look at the existing codebase to understand the patterns and conventions we follow.
## Commit Messages
The [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification is a
lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit
commit history, which makes it easier to write automated tools on top of. This convention dovetails with SemVer
by describing the features, fixes, and breaking changes made in commit messages. Please refer to the linked
documentation for examples and additional context.
<code>&lt;type&gt;[optional scope]: &lt;description&gt;
[optional body]
[optional footer(s)]
</code>
## Issue Tracking
We utilize the issue tracking functionality of GitHub to manage our project's roadmap and track bugs or feature requests.
If you encounter any problems or have a new idea, please search the issues to ensure it hasn't already been reported.
If necessary, open a new issue providing a clear description, steps to reproduce, and any relevant information.
We greatly appreciate your effort and contribution to our project! Let's build something awesome together!
35 changes: 5 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,13 @@ First, ensure you have installed the following tools locally
git clone https://github.com/aws-solutions-library-samples/osml-model-runner-test.git
```

2. Run `tox` to create a virtual environment
1. Run `tox` to create a virtual environment

```sh
cd osml-model-runner-test
tox
```



### Documentation

You can find documentation for this library in the `./doc` directory. Sphinx is used to construct a searchable HTML
Expand All @@ -50,30 +48,6 @@ version of the API documents.
tox -e docs
```


## Linting/Formatting

This package uses a number of tools to enforce formatting, linting, and general best practices:

- [black](https://github.com/psf/black)
- [isort](https://github.com/PyCQA/isort) for formatting with a max line length of 100
- [mypy](https://github.com/pre-commit/mirrors-mypy) to enforce static type checking
- [flake8](https://github.com/PyCQA/flake8) to check pep8 compliance and logical errors in code
- [autopep](https://github.com/pre-commit/mirrors-autopep8) to check pep8 compliance and logical errors in code
- [eslint](https://github.com/pre-commit/mirrors-eslint) to check pep8 compliance and logical errors in code
- [prettier](https://github.com/pre-commit/mirrors-prettier) to check pep8 compliance and logical errors in code
- [pre-commit](https://github.com/pre-commit/pre-commit-hooks) to install and control linters in githooks

```bash
python3 -m pip install pre-commit
pre-commit install
```

Additionally, you can perform linting on all the files in the package by running:
```bash
pre-commit run --all-files --show-diff-on-failure
```

### Build and Local Testing

You can run the hydra tests against your dev account by exporting the required parameters and using the pytest CLI by
Expand Down Expand Up @@ -112,14 +86,15 @@ python3 bin/process_image.py --help
```

### Running Tests in Docker
Arguments can be passed in to docker run in the same way that they are porvided to the shell script. For example, the container can be built and run as follows:
Arguments can be passed in to docker run in the same way that they are provided to the shell script.
For example, the container can be built and run as follows:

```
docker build . -t model-runner-hydra-test:latest
docker run -v ~/.aws:/root/.aws model-runner-hydra-test:latest small centerpoint NITF JPEG us-west-2 $ACCOUNT_NUMBER
```

Credentials from the users account are volume mounted into the container's root directory.
Credentials from the user's account are volume mounted into the container's root directory.

### Running LoadTest

Expand All @@ -144,7 +119,7 @@ If you are interested in contributing to OversightML Model Runner, see the [CONT

## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
See [CONTRIBUTING](CONTRIBUTING.md) for more information.

## License

Expand Down
Binary file added images/release-deployment.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/release_deployment.sketch
View file
Binary file not shown.

0 comments on commit 8ce7dd5

Please sign in to comment.