[Refactor] Model Checklist Document #2043
Open
+118
−59
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update. |
pcuenca
reviewed
Nov 11, 2025
docs/hub/model-release-checklist.md
Outdated
|
|
||
| ### Uploading Weights | ||
| - **Use separate repositories for different model weights**: | ||
| Create individual repositories for each variant of the same architecture. This lets you group them into a [collection](https://huggingface.co/docs/hub/en/collections), which users prefer when browsing many options. It also improves visibility because each model has its own URL (`hf.co/org/model-name`) and is easier to search. |
Member
There was a problem hiding this comment.
Suggested change
| Create individual repositories for each variant of the same architecture. This lets you group them into a [collection](https://huggingface.co/docs/hub/en/collections), which users prefer when browsing many options. It also improves visibility because each model has its own URL (`hf.co/org/model-name`) and is easier to search. | |
| Create individual repositories for each variant of the same architecture. This lets you group them into a [collection](https://huggingface.co/docs/hub/en/collections), which are easier to navigate than directory listings. It also improves visibility because each model has its own URL (`hf.co/org/model-name`), makes search easier, and provides download counts for each one of your models. |
Member
There was a problem hiding this comment.
not sure if needed but we could also mention that it makes it easier to integrate with downstream libraries too.
Contributor
Author
There was a problem hiding this comment.
@Vaibhavs10 how do you mean? I thought downstream libraries only benefit from transformers integration. If you could guide me into understanding this point better I will add it here.
Vaibhavs10
reviewed
Nov 12, 2025
Member
Vaibhavs10
left a comment
Vaibhavs10
left a comment
There was a problem hiding this comment.
very cool! thanks for the update, agree with most of the comments Pedro made and left a few suggestions.
docs/hub/model-release-checklist.md
Outdated
|
|
||
| ### Uploading Weights | ||
| - **Use separate repositories for different model weights**: | ||
| Create individual repositories for each variant of the same architecture. This lets you group them into a [collection](https://huggingface.co/docs/hub/en/collections), which users prefer when browsing many options. It also improves visibility because each model has its own URL (`hf.co/org/model-name`) and is easier to search. |
Member
There was a problem hiding this comment.
not sure if needed but we could also mention that it makes it easier to integrate with downstream libraries too.
docs/hub/model-release-checklist.md
Outdated
|
|
||
| Bonus: a recognised library also allows you to track downloads of your model over time. | ||
| > [!NOTE] | ||
| > A recognised library also allows you to track downloads of your model over time. |
Member
There was a problem hiding this comment.
maybe we could link this in the registered library bit: https://huggingface.co/docs/hub/en/models-adding-libraries
pcuenca
approved these changes
Nov 13, 2025
| ### Write a Comprehensive Model Card | ||
|
|
||
| ### Writing a Comprehensive Model Card | ||
| A well-crafted model card (the `README.md` in your repository) is essential for discoverability, reproducibility, and effective sharing. Include: |
Member
There was a problem hiding this comment.
Suggested change
| A well-crafted model card (the `README.md` in your repository) is essential for discoverability, reproducibility, and effective sharing. Include: | |
| A well-crafted model card (the `README.md` in your repository) is essential for discoverability, reproducibility, and effective sharing. Make sure to cover: |
(there's another include in the following section)
| To make the process more seamless, click **Import model card template** to pre-fill the `README.md`s with placeholders. | ||
|
|
||
| 1. **Library Integration**: If possible, add support for one of the many [libraries integrated with the Hugging Face Hub](https://huggingface.co/docs/hub/models-libraries) (such as Transformers or Diffusers). This integration significantly increases your model's accessibility and provides users with code snippets for working with your model. | ||
| |  |  | |
Member
There was a problem hiding this comment.
Not sure how this will render in a table, given that the left button is very wide. I tried to check here, but images are not shown for some reason:
| | Code snippet tab | | ||
|
|
||
| Finally, you can adopt the [Mixin class](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) when pushing custom PyTorch models. | ||
| You can also [create your own model library](https://huggingface.co/docs/hub/en/models-adding-libraries) or add Hub support to your library and codebase so they know how to download model weights from the Hub. |
Member
There was a problem hiding this comment.
Suggested change
| You can also [create your own model library](https://huggingface.co/docs/hub/en/models-adding-libraries) or add Hub support to your library and codebase so they know how to download model weights from the Hub. | |
| You can also [register your own model library](https://huggingface.co/docs/hub/en/models-adding-libraries) or add Hub support to your library and codebase so they know how to download model weights from the Hub. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
To note: I have added an
assetsfolder, which will be deleted later, once I have a green signal on the assets. I will add the assets to the hub, and link the URL.The PR is made to refactor the current model checklist, with an idea of being more concise and actionable insights. I felt the doc also did not have example images, so have added them.
I am open to feedback as this has not been reviewed by and HF team member in the past, so I am open to closing it as well if there is no need of this at the current moment. 🤗