diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bbd773419..f96fb0c81 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,87 @@ -## Contributing to YOLOv5 πŸš€ +Ultralytics logo -We love your input! We want to make contributing to YOLOv5 as easy and transparent as possible, whether it's: +# Contributing to YOLO πŸš€ + +We value your input and are committed to making contributing to YOLO as easy and transparent as possible. Whether you're: - Reporting a bug -- Discussing the current state of the code +- Discussing the current state of the codebase - Submitting a fix - Proposing a new feature -- Becoming a maintainer +- Interested in becoming a maintainer -YOLOv5 works so well due to our combined community effort, and for every small improvement you contribute you will be helping push the frontiers of what's possible in AI πŸ˜ƒ! +Ultralytics YOLO thrives thanks to the collective efforts of our community. Every improvement you contribute helps push the boundaries of what's possible in AI! πŸ˜ƒ -## Submitting a Pull Request (PR) πŸ› οΈ +## πŸ› οΈ Submitting a Pull Request (PR) -Submitting a PR is easy! This example shows how to submit a PR for updating `requirements.txt` in 4 steps: +Submitting a PR is straightforward! Here’s an example showing how to update `requirements.txt` in four simple steps: -### 1. Select File to Update +### 1. Select the File to Update -Select `requirements.txt` to update by clicking on it in GitHub. +Click on `requirements.txt` in the GitHub repository.

PR_step1

### 2. Click 'Edit this file' -The button is in the top-right corner. +Find the 'Edit this file' button in the top-right corner.

PR_step2

-### 3. Make Changes +### 3. Make Your Changes -Change the `matplotlib` version from `3.2.2` to `3.3`. +For example, update the `matplotlib` version from `3.2.2` to `3.3`.

PR_step3

-### 4. Preview Changes and Submit PR +### 4. Preview Changes and Submit Your PR -Click on the **Preview changes** tab to verify your updates. At the bottom of the screen select 'Create a **new branch** for this commit', assign your branch a descriptive name such as `fix/matplotlib_version` and click the green **Propose changes** button. All done, your PR is now submitted to YOLOv5 for review and approval πŸ˜ƒ! +Click the **Preview changes** tab to review your updates. At the bottom, select 'Create a new branch for this commit', give your branch a descriptive name like `fix/matplotlib_version`, and click the green **Propose changes** button. Your PR is now submitted for review! πŸ˜ƒ

PR_step4

-### PR recommendations +### PR Best Practices -To allow your work to be integrated as seamlessly as possible, we advise you to: +To ensure your work is integrated smoothly, please: -- βœ… Verify your PR is **up-to-date** with `ultralytics/yolov5` `master` branch. If your PR is behind you can update your code by clicking the 'Update branch' button or by running `git pull` and `git merge master` locally. +- βœ… Make sure your PR is **up-to-date** with the `ultralytics/yolov5` `master` branch. If your branch is behind, update it using the 'Update branch' button or by running `git pull` and `git merge master` locally.

Screenshot 2022-08-29 at 22 47 15

-- βœ… Verify all YOLOv5 Continuous Integration (CI) **checks are passing**. +- βœ… Ensure all YOLO Continuous Integration (CI) **checks are passing**.

Screenshot 2022-08-29 at 22 47 03

-- βœ… Reduce changes to the absolute **minimum** required for your bug fix or feature addition. _"It is not daily increase but daily decrease, hack away the unessential. The closer to the source, the less wastage there is."_ β€” Bruce Lee +- βœ… Limit your changes to the **minimum** required for your bug fix or feature. + _"It is not daily increase but daily decrease, hack away the unessential. The closer to the source, the less wastage there is."_ β€” Bruce Lee -## Submitting a Bug Report πŸ› +## πŸ› Submitting a Bug Report -If you spot a problem with YOLOv5 please submit a Bug Report! +If you encounter an issue with YOLO, please submit a bug report! -For us to start investigating a possible problem we need to be able to reproduce it ourselves first. We've created a few short guidelines below to help users provide what we need to get started. +To help us investigate, we need to be able to reproduce the problem. Follow these guidelines to provide what we need to get started: -When asking a question, people will be better able to provide help if you provide **code** that they can easily understand and use to **reproduce** the problem. This is referred to by community members as creating a [minimum reproducible example](https://docs.ultralytics.com/help/minimum-reproducible-example/). Your code that reproduces the problem should be: +When asking a question or reporting a bug, you'll get better help if you provide **code** that others can easily understand and use to **reproduce** the issue. This is known as a [minimum reproducible example](https://docs.ultralytics.com/help/minimum-reproducible-example/). Your code should be: -- βœ… **Minimal** – Use as little code as possible that still produces the same problem -- βœ… **Complete** – Provide **all** parts someone else needs to reproduce your problem in the question itself -- βœ… **Reproducible** – Test the code you're about to provide to make sure it reproduces the problem +- βœ… **Minimal** – Use as little code as possible that still produces the issue +- βœ… **Complete** – Include all parts needed for someone else to reproduce the problem +- βœ… **Reproducible** – Test your code to ensure it actually reproduces the issue -In addition to the above requirements, for [Ultralytics](https://www.ultralytics.com/) to provide assistance your code should be: +Additionally, for [Ultralytics](https://www.ultralytics.com/) to assist you, your code should be: -- βœ… **Current** – Verify that your code is up-to-date with the current GitHub [master](https://github.com/ultralytics/yolov5/tree/master), and if necessary `git pull` or `git clone` a new copy to ensure your problem has not already been resolved by previous commits. -- βœ… **Unmodified** – Your problem must be reproducible without any modifications to the codebase in this repository. [Ultralytics](https://www.ultralytics.com/) does not provide support for custom code ⚠️. +- βœ… **Current** – Ensure your code is up-to-date with the latest [master branch](https://github.com/ultralytics/yolov5/tree/master). Use `git pull` or `git clone` to get the latest version and confirm your issue hasn't already been fixed. +- βœ… **Unmodified** – The problem must be reproducible without any custom modifications to the repository. [Ultralytics](https://www.ultralytics.com/) does not provide support for custom code ⚠️. -If you believe your problem meets all of the above criteria, please close this issue and raise a new one using the πŸ› **Bug Report** [template](https://github.com/ultralytics/yolov5/issues/new/choose) and provide a [minimum reproducible example](https://docs.ultralytics.com/help/minimum-reproducible-example/) to help us better understand and diagnose your problem. +If your issue meets these criteria, please close your current issue and open a new one using the πŸ› **Bug Report** [template](https://github.com/ultralytics/yolov5/issues/new/choose), including your [minimum reproducible example](https://docs.ultralytics.com/help/minimum-reproducible-example/) to help us diagnose your problem. -## License +## πŸ“„ License -By contributing, you agree that your contributions will be licensed under the [AGPL-3.0 license](https://choosealicense.com/licenses/agpl-3.0/) +By contributing, you agree that your contributions will be licensed under the [AGPL-3.0 license](https://choosealicense.com/licenses/agpl-3.0/). + +--- + +For more details on contributing, check out the [Ultralytics open-source contributing guide](https://docs.ultralytics.com/help/contributing/), and explore our [Ultralytics blog](https://www.ultralytics.com/blog) for community highlights and best practices. + +We welcome your contributionsβ€”thank you for helping make Ultralytics YOLO better! πŸš€ + +[![Ultralytics open-source contributors](https://raw.githubusercontent.com/ultralytics/assets/main/im/image-contributors.png)](https://github.com/ultralytics/ultralytics/graphs/contributors) diff --git a/utils/loggers/comet/README.md b/utils/loggers/comet/README.md index 63d578c52..83cb20027 100644 --- a/utils/loggers/comet/README.md +++ b/utils/loggers/comet/README.md @@ -37,8 +37,8 @@ You can configure Comet in two ways: Set your credentials directly in your environment. ```shell - export COMET_API_KEY= - export COMET_PROJECT_NAME= # Defaults to 'yolov5' if not set + export COMET_API_KEY=YOUR_COMET_API_KEY + export COMET_PROJECT_NAME=YOUR_COMET_PROJECT_NAME # Defaults to 'yolov5' if not set ``` Find your API key in your [Comet Account Settings](https://www.comet.com/site/). @@ -48,8 +48,8 @@ You can configure Comet in two ways: ```ini [comet] - api_key= - project_name= # Defaults to 'yolov5' if not set + api_key=YOUR_COMET_API_KEY + project_name=YOUR_COMET_PROJECT_NAME # Defaults to 'yolov5' if not set ``` ### Run the Training Script @@ -102,14 +102,14 @@ Customize Comet's logging behavior using command-line flags or environment varia ```shell # Environment Variables for Comet Configuration -export COMET_MODE=online # 'online' or 'offline'. Default: online -export COMET_MODEL_NAME= # Name for the saved model. Default: yolov5 -export COMET_LOG_CONFUSION_MATRIX=false # Disable confusion matrix logging. Default: true -export COMET_MAX_IMAGE_UPLOADS= # Max prediction images to log. Default: 100 -export COMET_LOG_PER_CLASS_METRICS=true # Log metrics per class. Default: false -export COMET_DEFAULT_CHECKPOINT_FILENAME= # Checkpoint for resuming. Default: 'last.pt' -export COMET_LOG_BATCH_LEVEL_METRICS=true # Log training metrics per batch. Default: false -export COMET_LOG_PREDICTIONS=true # Disable prediction logging if set to false. Default: true +export COMET_MODE=online # 'online' or 'offline'. Default: online +export COMET_MODEL_NAME=YOUR_MODEL_NAME # Name for the saved model. Default: yolov5 +export COMET_LOG_CONFUSION_MATRIX=false # Disable confusion matrix logging. Default: true +export COMET_MAX_IMAGE_UPLOADS=NUMBER # Max prediction images to log. Default: 100 +export COMET_LOG_PER_CLASS_METRICS=true # Log metrics per class. Default: false +export COMET_DEFAULT_CHECKPOINT_FILENAME=checkpoint_file.pt # Checkpoint for resuming. Default: 'last.pt' +export COMET_LOG_BATCH_LEVEL_METRICS=true # Log training metrics per batch. Default: false +export COMET_LOG_PREDICTIONS=true # Disable prediction logging if set to false. Default: true ``` For more configuration options, see the [Comet documentation](https://www.comet.com/docs/v2/). @@ -208,7 +208,7 @@ To use a dataset stored in Comet Artifacts, update the `path` in your dataset YA ```yaml # contents of artifact.yaml -path: "comet:///:" +path: "comet://WORKSPACE_NAME/ARTIFACT_NAME:ARTIFACT_VERSION_OR_ALIAS" train: images/train # Adjust subdirectory if needed val: images/val # Adjust subdirectory if needed @@ -231,13 +231,13 @@ Artifacts track data lineage, showing which experiments used specific dataset ve ## πŸ”„ Resuming Training Runs -If a training run is interrupted (for example, due to connection issues), you can resume it using the `--resume` flag with the Comet Run Path (`comet:////`). +If a training run is interrupted (for example, due to connection issues), you can resume it using the `--resume` flag with the Comet Run Path (`comet://YOUR_WORKSPACE/YOUR_PROJECT/EXPERIMENT_ID`). This restores the model state, hyperparameters, arguments, and downloads necessary Artifacts, continuing logging to the existing Comet Experiment. Learn more about [resuming runs in the Comet documentation](https://www.comet.com/docs/v2/guides/experiment-management/resume-experiment/). ```shell python train.py \ - --resume "comet:////" + --resume "comet://YOUR_WORKSPACE/YOUR_PROJECT/EXPERIMENT_ID" ``` ## πŸ” Hyperparameter Optimization (HPO) @@ -270,10 +270,10 @@ Execute multiple sweep trials concurrently using the `comet optimizer` command: ```shell comet optimizer -j \ - utils/loggers/comet/hpo.py < num_workers > utils/loggers/comet/optimizer_config.json + utils/loggers/comet/hpo.py NUM_WORKERS utils/loggers/comet/optimizer_config.json ``` -Replace `` with the desired number of parallel processes. +Replace `NUM_WORKERS` with the desired number of parallel processes. ### Visualizing HPO Results