Skip to content

Commit 9c1429c

Browse files
jaeyounkimjaeyounkim
authored
Add new templates and update README files (#8467)
* Update README.md Add a new section (Announcements) * Update README.md Remove description columns from tables Remove guidelines sections * Update CONTRIBUTING.md Add a link to the wiki for guidelines * Create README_TEMPLATE.md Add a README template file for a new model * Create pull_request_template.md Add a new template for a pull request * Update README.md Add a table of contents Add a new section for archived models and implementations * Update README.md Revise "Contributions" * Update README.md Update the link to the contribution guidelines * Update README.md Update the link to the contribution guidelines. * Update README.md Update the link to the contribution guidelines. * Update README.md Update the link to the contribution guidelines.
1 parent 7194391 commit 9c1429c

File tree

7 files changed

+331
-160
lines changed

7 files changed

+331
-160
lines changed

Diff for: ‎.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Description
2+
3+
> :memo: Please include a summary of the change.
4+
>
5+
> * Please also include relevant motivation and context.
6+
> * List any dependencies that are required for this change.
7+
8+
## Type of change
9+
10+
Please delete options that are not relevant.
11+
12+
- [ ] Bug fix (non-breaking change which fixes an issue)
13+
- [ ] Documentation update
14+
- [ ] TensorFlow 2 migration
15+
- [ ] New feature (non-breaking change which adds functionality)
16+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
17+
- [ ] A new research paper code implementation
18+
19+
## Tests
20+
21+
> :memo: Please describe the tests that you ran to verify your changes.
22+
>
23+
> * Provide instructions so we can reproduce.
24+
> * Please also list any relevant details for your test configuration.
25+
26+
**Test Configuration**:
27+
28+
## Checklist
29+
30+
- [ ] I have signed the [Contributor License Agreement](../../wiki/Contributor-License-Agreements).
31+
- [ ] I have read [guidelines for pull request](../../wiki/Submitting-a-pull-request).
32+
- [ ] My code follows the [coding guidelines](../../wiki/Coding-Guidelines).
33+
- [ ] I have performed a self [code review](../../wiki/Code-review) of my own code.
34+
- [ ] I have commented my code, particularly in hard-to-understand areas.
35+
- [ ] I have made corresponding changes to the documentation.
36+
- [ ] My changes generate no new warnings.
37+
- [ ] I have added tests that prove my fix is effective or that my feature works.

Diff for: ‎.github/README_TEMPLATE.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
> :memo: A README.md template for releasing a paper code implementation to a GitHub repository.
2+
>
3+
> * Template version: 1.0.2020.125
4+
> * Please modify sections depending on needs.
5+
6+
# Model name, Paper title, or Project Name
7+
8+
> :memo: Add a badge for the ArXiv identifier of your paper (arXiv:YYMM.NNNNN)
9+
10+
[![Paper](http://img.shields.io/badge/paper-arXiv.YYMM.NNNNN-B3181B.svg)](https://arxiv.org/abs/...)
11+
12+
This repository is the official or unofficial implementation of the following paper.
13+
14+
* Paper title: [Paper Title](https://arxiv.org/abs/YYMM.NNNNN)
15+
16+
## Description
17+
18+
> :memo: Provide description of the model.
19+
>
20+
> * Provide brief information of the algorithms used.
21+
> * Provide links for demos, blog posts, etc.
22+
23+
## History
24+
25+
> :memo: Provide a changelog.
26+
27+
## Maintainers
28+
29+
> :memo: Provide maintainer information.
30+
31+
* Last name, First name ([@GitHub username](https://github.com/username))
32+
* Last name, First name ([@GitHub username](https://github.com/username))
33+
34+
## Table of Contents
35+
36+
> :memo: Provide a table of contents to help readers navigate a lengthy README document.
37+
38+
## Requirements
39+
40+
[![tensorFlow 2.1+](https://img.shields.io/badge/TensorFlow-2.1-brightgreen)](https://github.com/tensorflow/tensorflow/releases/tag/v2.1.0)
41+
[![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/)
42+
43+
> :memo: Provide details of the software required.
44+
>
45+
> * Add a `requirements.txt` file to the root directory for installing the necessary dependencies.
46+
> * Describe how to install requirements using pip.
47+
> * Alternatively, create INSTALL.md.
48+
49+
To install requirements:
50+
51+
```setup
52+
pip install -r requirements.txt
53+
```
54+
55+
## Results
56+
57+
> :memo: Provide a table with results. (e.g., accuracy, latency)
58+
>
59+
> * Provide links to the pre-trained models (checkpoint, SavedModel files).
60+
> * Publish TensorFlow SavedModel files on TensorFlow Hub (tfhub.dev) if possible.
61+
> * Add links to [TensorBoard.dev](https://tensorboard.dev/) for visualizing metrics.
62+
>
63+
> An example table for image classification results
64+
>
65+
> ### Image Classification
66+
>
67+
> | Model name | Download | Top 1 Accuracy | Top 5 Accuracy |
68+
> |------------|----------|----------------|----------------|
69+
> | Model name | [Checkpoint](https://drive.google.com/...), [SavedModel](https://tfhub.dev/...) | xx% | xx% |
70+
71+
## Dataset
72+
73+
> :memo: Provide information of the dataset used.
74+
75+
## Training
76+
77+
> :memo: Provide training information.
78+
>
79+
> * Provide details for preprocessing, hyperparameters, random seeds, and environment.
80+
> * Provide a command line example for training.
81+
82+
Please run this command line for training.
83+
84+
```shell
85+
python3 ...
86+
```
87+
88+
## Evaluation
89+
90+
> :memo: Provide an evaluation script with details of how to reproduce results.
91+
>
92+
> * Describe data preprocessing / postprocessing steps.
93+
> * Provide a command line example for evaluation.
94+
95+
Please run this command line for evaluation.
96+
97+
```shell
98+
python3 ...
99+
```
100+
101+
## References
102+
103+
> :memo: Provide links to references.
104+
105+
## License
106+
107+
> :memo: Place your license text in a file named LICENSE in the root of the repository.
108+
>
109+
> * Include information about your license.
110+
> * Reference: [Adding a license to a repository](https://help.github.com/en/github/building-a-strong-community/adding-a-license-to-a-repository)
111+
112+
This project is licensed under the terms of the **Apache License 2.0**.
113+
114+
## Citation
115+
116+
> :memo: Make your repository citable.
117+
>
118+
> * Reference: [Making Your Code Citable](https://guides.github.com/activities/citable-code/)
119+
120+
If you want to cite this repository in your research paper, please use the following information.

Diff for: ‎CONTRIBUTING.md

+5-21
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,10 @@
1-
# Contributing guidelines
1+
# How to contribute
22

3-
If you have created a model and would like to publish it here, please send us a
4-
pull request. For those just getting started with pull requests, GitHub has a
5-
[howto](https://help.github.com/articles/using-pull-requests/).
3+
![Contributors](https://img.shields.io/github/contributors/tensorflow/models)
64

7-
The code for any model in this repository is licensed under the Apache License
8-
2.0.
5+
We encourage you to contribute to the TensorFlow Model Garden.
96

10-
In order to accept our code, we have to make sure that we can publish your code:
11-
You have to sign a Contributor License Agreement (CLA).
7+
Please read our [guidelines](../../wiki/How-to-contribute) for details.
128

13-
***NOTE***: Only [code owners](./CODEOWNERS) are allowed to merge a pull request.
9+
**NOTE**: Only [code owners](./CODEOWNERS) are allowed to merge a pull request.
1410
Please contact the code owners of each model to merge your pull request.
15-
16-
### Contributor License Agreements
17-
18-
Please fill out either the individual or corporate Contributor License Agreement (CLA).
19-
20-
* If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an [individual CLA](http://code.google.com/legal/individual-cla-v1.0.html).
21-
* If you work for a company that wants to allow you to contribute your work, then you'll need to sign a [corporate CLA](http://code.google.com/legal/corporate-cla-v1.0.html).
22-
23-
Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests.
24-
25-
***NOTE***: Only original source code from you and other people that have signed the CLA can be accepted into the repository.
26-

Diff for: ‎README.md

+9-7
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,19 @@
44

55
The TensorFlow Model Garden is a repository with a number of different implementations of state-of-the-art (SOTA) models and modeling solutions for TensorFlow users. We aim to demonstrate the best practices for modeling so that TensorFlow users can take full advantage of TensorFlow for their research and product development.
66

7-
## Structure
8-
9-
| Folder | Description |
7+
| Directory | Description |
108
|-----------|-------------|
11-
| [official](official) | • **A collection of example implementations for SOTA models using the latest TensorFlow 2's high-level APIs**<br />• Officially maintained, supported, and kept up to date with the latest TensorFlow 2 APIs<br />• Reasonably optimized for fast performance while still being easy to read |
12-
| [research](research) | • A collection of research model implementations in TensorFlow 1 or 2 by researchers<br />• Up to the individual researchers to maintain the model implementations and/or provide support on issues and pull requests |
9+
| [official](official) | • A collection of example implementations for SOTA models using the latest TensorFlow 2's high-level APIs<br />• Officially maintained, supported, and kept up to date with the latest TensorFlow 2 APIs by TensorFlow<br />• Reasonably optimized for fast performance while still being easy to read |
10+
| [research](research) | • A collection of research model implementations in TensorFlow 1 or 2 by researchers<br />• Maintained and supported by researchers |
1311
| [community](community) | • A curated list of the GitHub repositories with machine learning models and implementations powered by TensorFlow 2 |
1412

15-
## Contribution guidelines
13+
## [Announcements](../../wiki/Announcements)
14+
15+
* March 31, 2020: [Introducing the Model Garden for TensorFlow 2](https://blog.tensorflow.org/2020/03/introducing-model-garden-for-tensorflow-2.html) ([Tweet](https://twitter.com/TensorFlow/status/1245029834633297921))
16+
17+
## Contributions
1618

17-
If you want to contribute to models, please review the [contribution guidelines](CONTRIBUTING.md).
19+
If you want to contribute, please review the [contribution guidelines](../../wiki/How-to-contribute).
1820

1921
## License
2022

Diff for: ‎community/README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
This repository provides a curated list of the GitHub repositories with machine learning models and implementations powered by TensorFlow 2.
66

7-
**Disclosure**: Contributing companies or individuals are responsible for maintaining their repositories.
7+
**Note**: Contributing companies or individuals are responsible for maintaining their repositories.
88

99
## Models / Implementations
1010

@@ -16,6 +16,6 @@ This repository provides a curated list of the GitHub repositories with machine
1616
| [Mask R-CNN](https://github.com/NVIDIA/DeepLearningExamples/tree/master/TensorFlow2/Segmentation/MaskRCNN) | [Mask R-CNN](https://arxiv.org/abs/1703.06870) | • Automatic Mixed Precision<br/>• Multi-GPU training support with Horovod<br/>• TensorRT | [NVIDIA](https://github.com/NVIDIA) |
1717
| [U-Net Medical Image Segmentation](https://github.com/NVIDIA/DeepLearningExamples/tree/master/TensorFlow2/Segmentation/UNet_Medical) | [U-Net: Convolutional Networks for Biomedical Image Segmentation](https://arxiv.org/abs/1505.04597) | • Automatic Mixed Precision<br/>• Multi-GPU training support with Horovod<br/>• TensorRT | [NVIDIA](https://github.com/NVIDIA) |
1818

19-
2019
## Contributions
21-
If you have a suggestion for the community model repository, please submit a pull request.
20+
21+
If you want to contribute, please review the [contribution guidelines](../../../wiki/How-to-contribute).

Diff for: ‎official/README.md

+49-60
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,68 @@ The TensorFlow official models are a collection of models
66
that use TensorFlow’s high-level APIs.
77
They are intended to be well-maintained, tested, and kept up to date
88
with the latest TensorFlow API.
9+
910
They should also be reasonably optimized for fast performance while still
1011
being easy to read.
1112
These models are used as end-to-end tests, ensuring that the models run
1213
with the same or improved speed and performance with each new TensorFlow build.
1314

14-
## Model Implementations
15+
## More models to come!
1516

16-
### Natural Language Processing
17+
The team is actively developing new models.
18+
In the near future, we will add:
19+
20+
* State-of-the-art language understanding models:
21+
More members in Transformer family
22+
* Start-of-the-art image classification models:
23+
EfficientNet, MnasNet, and variants
24+
* A set of excellent objection detection models.
25+
26+
## Table of Contents
1727

18-
| Model | Description | Reference |
19-
| ----- | ----------- | --------- |
20-
| [ALBERT](nlp/albert) | A Lite BERT for Self-supervised Learning of Language Representations | [arXiv:1909.11942](https://arxiv.org/abs/1909.11942) |
21-
| [BERT](nlp/bert) | A powerful pre-trained language representation model: BERT (Bidirectional Encoder Representations from Transformers) | [arXiv:1810.04805](https://arxiv.org/abs/1810.04805) |
22-
| [NHNet](nlp/nhnet) | A transformer-based multi-sequence to sequence model: Generating Representative Headlines for News Stories | [arXiv:2001.09386](https://arxiv.org/abs/2001.09386) |
23-
| [Transformer](nlp/transformer) | A transformer model to translate the WMT English to German dataset | [arXiv:1706.03762](https://arxiv.org/abs/1706.03762) |
24-
| [XLNet](nlp/xlnet) | XLNet: Generalized Autoregressive Pretraining for Language Understanding | [arXiv:1906.08237](https://arxiv.org/abs/1906.08237) |
28+
- [Models and Implementations](#models-and-implementations)
29+
* [Computer Vision](#computer-vision)
30+
+ [Image Classification](#image-classification)
31+
+ [Object Detection and Segmentation](#object-detection-and-segmentation)
32+
* [Natural Language Processing](#natural-language-processing)
33+
* [Recommendation](#recommendation)
34+
- [How to get started with the official models](#how-to-get-started-with-the-official-models)
35+
36+
## Models and Implementations
2537

2638
### Computer Vision
2739

28-
| Model | Description | Reference |
29-
| ----- | ----------- | --------- |
30-
| [MNIST](vision/image_classification) | A basic model to classify digits from the MNIST dataset | [Link](http://yann.lecun.com/exdb/mnist/) |
31-
| [ResNet](vision/image_classification) | A deep residual network for image recognition | [arXiv:1512.03385](https://arxiv.org/abs/1512.03385) |
32-
| [RetinaNet](vision/detection) | A fast and powerful object detector | [arXiv:1708.02002](https://arxiv.org/abs/1708.02002) |
33-
| [Mask R-CNN](vision/detection) | An object detection and instance segmentation model | [arXiv:1703.06870](https://arxiv.org/abs/1703.06870) |
40+
#### Image Classification
41+
42+
| Model | Reference (Paper) |
43+
|-------|-------------------|
44+
| [MNIST](vision/image_classification) | A basic model to classify digits from the [MNIST dataset](http://yann.lecun.com/exdb/mnist/) |
45+
| [ResNet](vision/image_classification) | [Deep Residual Learning for Image Recognition](https://arxiv.org/abs/1512.03385) |
3446

35-
### Other models
47+
#### Object Detection and Segmentation
3648

37-
| Model | Description | Reference |
38-
| ----- | ----------- | --------- |
39-
| [NCF](recommendation) | Neural Collaborative Filtering model for recommendation tasks | [arXiv:1708.05031](https://arxiv.org/abs/1708.05031) |
49+
| Model | Reference (Paper) |
50+
|-------|-------------------|
51+
| [RetinaNet](vision/detection) | [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002) |
52+
| [Mask R-CNN](vision/detection) | [Mask R-CNN](https://arxiv.org/abs/1703.06870) |
53+
54+
### Natural Language Processing
4055

41-
---
56+
| Model | Reference (Paper) |
57+
|-------|-------------------|
58+
| [ALBERT (A Lite BERT)](nlp/albert) | [ALBERT: A Lite BERT for Self-supervised Learning of Language Representations](https://arxiv.org/abs/1909.11942) |
59+
| [BERT (Bidirectional Encoder Representations from Transformers)](nlp/bert) | [BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding](https://arxiv.org/abs/1810.04805) |
60+
| [NHNet (News Headline generation model)](nlp/nhnet) | [Generating Representative Headlines for News Stories](https://arxiv.org/abs/2001.09386) |
61+
| [Transformer](nlp/transformer) | [Attention Is All You Need](https://arxiv.org/abs/1706.03762) |
62+
| [XLNet](nlp/xlnet) | [XLNet: Generalized Autoregressive Pretraining for Language Understanding](https://arxiv.org/abs/1906.08237) |
4263

43-
## How to get started with the Model Garden official models
64+
### Recommendation
65+
66+
| Model | Reference (Paper) |
67+
|-------|-------------------|
68+
| [NCF](recommendation) | [Neural Collaborative Filtering](https://arxiv.org/abs/1708.05031) |
69+
70+
## How to get started with the official models
4471

4572
* The models in the master branch are developed using TensorFlow 2,
4673
and they target the TensorFlow [nightly binaries](https://github.com/tensorflow/tensorflow#installation)
@@ -108,44 +135,6 @@ os.environ['PYTHONPATH'] += ":/path/to/models"
108135
pip3 install --user -r official/requirements.txt
109136
```
110137

111-
---
112-
113-
## More models to come!
114-
115-
The team is actively developing new models.
116-
In the near future, we will add:
117-
118-
- State-of-the-art language understanding models:
119-
More members in Transformer family
120-
- Start-of-the-art image classification models:
121-
EfficientNet, MnasNet and variants.
122-
- A set of excellent objection detection models.
123-
124-
If you would like to make any fixes or improvements to the models, please
125-
[submit a pull request](https://github.com/tensorflow/models/compare).
126-
127-
---
128-
129138
## Contributions
130139

131-
Every model should follow our guidelines to uphold our objectives of readable,
132-
usable, and maintainable code.
133-
134-
### General Guidelines
135-
136-
- Code should be well documented and tested.
137-
- Runnable from a blank environment with ease.
138-
- Trainable on: single GPU/CPU (baseline), multiple GPUs & TPUs
139-
- Compatible with Python 3 (using [six](https://pythonhosted.org/six/)
140-
when being compatible with Python 2 is necessary)
141-
- Conform to
142-
[Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md)
143-
144-
### Implementation Guidelines
145-
146-
These guidelines are to ensure consistent model implementations for
147-
better readability and maintainability.
148-
149-
- Use [common utility functions](utils)
150-
- Export SavedModel at the end of the training.
151-
- Consistent flags and flag-parsing library ([read more here](utils/flags/guidelines.md))
140+
If you want to contribute, please review the [contribution guidelines](../../../wiki/How-to-contribute).

0 commit comments

Comments
 (0)