Skip to content

Commit 5f3b6e7

Browse files
esteiningeresteininger
committed
feat: Prepare for IAB Tech Lab contribution and v1.0.0 release
- Update license to BSD 2-Clause for IAB Tech Lab compatibility - Add formal donation letter and follow-up email templates - Enhance README with enablement-ready content and official samples - Create comprehensive CONTRIBUTING.md with development guidelines - Improve GitHub issue templates for better bug reports - Add official IAB sample datasets based on Content Taxonomy 2.2 - Update version to 1.0.0 and prepare release notes - Add enablement session materials for IAB member presentations This release marks the repository's readiness for formal contribution to IAB Tech Lab and industry-wide adoption of IAB 3.0 migration tools.
1 parent dfc91e3 commit 5f3b6e7

14 files changed

Lines changed: 1688 additions & 68 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,49 @@
11
---
22
name: Bug report
3-
about: Create a report to help us improve
3+
about: Report a bug in the IAB Mapper
44
labels: bug
5+
assignees: ''
56
---
67

78
**Describe the bug**
89
A clear and concise description of what the bug is.
910

1011
**To Reproduce**
1112
Steps to reproduce the behavior:
12-
1. ...
13-
2. ...
13+
1. Input data format (CSV/JSON)
14+
2. Command used
15+
3. Expected vs actual output
16+
17+
**Sample Data**
18+
If possible, provide a minimal example of the input data that causes the issue (anonymized):
19+
```csv
20+
code,label
21+
1-4,Sports
22+
```
1423

1524
**Expected behavior**
1625
What you expected to happen.
1726

27+
**Actual behavior**
28+
What actually happened.
29+
1830
**Screenshots/logs**
1931
If applicable, add screenshots or logs.
2032

2133
**Environment**
22-
- OS:
23-
- Python:
24-
- Package version:
34+
- OS: [e.g. macOS 14.0, Ubuntu 22.04, Windows 11]
35+
- Python: [e.g. 3.9, 3.10, 3.11]
36+
- Package version: [e.g. 0.3.2]
37+
- Installation method: [e.g. pip, from source]
38+
39+
**Mapping Configuration**
40+
- Fuzzy method used: [e.g. rapidfuzz, bm25, tfidf]
41+
- Fuzzy cutoff: [e.g. 0.92]
42+
- Embeddings enabled: [yes/no]
43+
- Embeddings model: [if applicable]
2544

2645
**Additional context**
27-
Add any other context about the problem here.
46+
Add any other context about the problem here, including:
47+
- Whether this affects specific IAB categories
48+
- If the issue occurs with certain input formats
49+
- Any workarounds you've found

‎CONTRIBUTING.md‎

Lines changed: 158 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,162 @@
1-
## Contributing
1+
# Contributing to IAB Mapper
22

3-
1. Fork and create a feature branch.
4-
2. Setup dev env: `python -m venv .venv && source .venv/bin/activate && pip install -e .[emb] && pip install -r requirements-dev.txt || pip install pytest`
5-
3. Run tests: `pytest -q`
6-
4. Open a PR with a concise description and screenshots/logs if helpful.
3+
Thank you for your interest in contributing to the IAB Mapper! This project helps the industry migrate from IAB Content Taxonomy 2.x to 3.0, and we welcome contributions from the community.
74

8-
### Commit style
9-
Use conventional commits where possible: `feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`.
5+
## 🚀 Getting Started
106

11-
### Reporting issues
12-
Please include reproduction steps, expected vs actual behavior, and environment details.
7+
### Development Setup
8+
9+
1. **Fork and clone** the repository
10+
```bash
11+
git clone https://github.com/your-username/iab-mapper.git
12+
cd iab-mapper
13+
```
14+
15+
2. **Create a virtual environment**
16+
```bash
17+
python -m venv .venv
18+
source .venv/bin/activate # On Windows: .venv\Scripts\activate
19+
```
20+
21+
3. **Install dependencies**
22+
```bash
23+
# Basic installation
24+
pip install -e .
25+
26+
# With embeddings support
27+
pip install -e ".[emb]"
28+
29+
# Development dependencies
30+
pip install -r requirements-dev.txt
31+
```
32+
33+
4. **Run tests** to ensure everything works
34+
```bash
35+
pytest -q
36+
```
37+
38+
5. **Create a feature branch**
39+
```bash
40+
git checkout -b feature/your-feature-name
41+
```
42+
43+
## 📝 Types of Contributions
44+
45+
### Bug Reports
46+
- Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)
47+
- Include reproduction steps, expected vs actual behavior, and environment details
48+
- Provide sample data if possible (anonymized)
49+
50+
### Feature Requests
51+
- Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md)
52+
- Explain the use case and expected behavior
53+
- Consider if the feature aligns with the project's scope
54+
55+
### Code Contributions
56+
- **Small fixes:** Direct PRs are welcome
57+
- **Larger features:** Open an issue first to discuss the approach
58+
- **Documentation:** Always welcome improvements to README, docstrings, or examples
59+
60+
## 🔧 Development Guidelines
61+
62+
### Code Style
63+
- Follow PEP 8 for Python code
64+
- Use type hints where appropriate
65+
- Add docstrings for new functions/classes
66+
- Keep functions focused and testable
67+
68+
### Commit Style
69+
Use conventional commits where possible:
70+
- `feat:` New features
71+
- `fix:` Bug fixes
72+
- `docs:` Documentation changes
73+
- `chore:` Maintenance tasks
74+
- `test:` Test additions/changes
75+
- `refactor:` Code refactoring
76+
- `perf:` Performance improvements
77+
78+
### Testing
79+
- Add tests for new functionality
80+
- Ensure existing tests pass: `pytest -q`
81+
- Test with sample data from the `demo/` directory
82+
- Consider edge cases and error conditions
83+
84+
### Pull Request Process
85+
86+
1. **Update documentation** if you change functionality
87+
2. **Add tests** for new features
88+
3. **Update CHANGELOG.md** with your changes
89+
4. **Ensure all tests pass**
90+
5. **Request review** from maintainers
91+
92+
### PR Description Template
93+
```markdown
94+
## Description
95+
Brief description of changes
96+
97+
## Type of Change
98+
- [ ] Bug fix
99+
- [ ] New feature
100+
- [ ] Documentation update
101+
- [ ] Performance improvement
102+
- [ ] Refactoring
103+
104+
## Testing
105+
- [ ] Tests pass locally
106+
- [ ] Added tests for new functionality
107+
- [ ] Tested with sample data
108+
109+
## Screenshots/Logs
110+
If applicable, add screenshots or logs showing the changes.
111+
```
112+
113+
## 🧪 Testing with Sample Data
114+
115+
The repository includes sample data in the `demo/` directory:
116+
- `sample_2x_codes.csv` - Small test dataset
117+
- `sample_2x_codes_large.csv` - Larger test dataset
118+
- `sample_2x_codes.json` - JSON format examples
119+
120+
Test your changes with:
121+
```bash
122+
# Test with small dataset
123+
iab-mapper demo/sample_2x_codes.csv -o test_output.json
124+
125+
# Test with larger dataset
126+
iab-mapper demo/sample_2x_codes_large.csv -o test_output_large.json
127+
```
128+
129+
## 📊 Performance Considerations
130+
131+
- The mapper processes data locally, so performance matters
132+
- Consider memory usage with large datasets
133+
- Embeddings can be memory-intensive - test with realistic data sizes
134+
- Profile changes that might affect processing speed
135+
136+
## 🔒 Security & Privacy
137+
138+
- This tool processes data locally - no external APIs by default
139+
- Be mindful of any changes that might introduce external dependencies
140+
- Ensure PII handling remains local-only
141+
- Test offline functionality
142+
143+
## 📞 Getting Help
144+
145+
- **Issues:** [GitHub Issues](https://github.com/mixpeek/iab-mapper/issues)
146+
- **Discussions:** Use GitHub Discussions for questions
147+
- **Documentation:** Check the [README](README.md) and inline docs
148+
149+
## 🎯 Project Goals
150+
151+
The IAB Mapper aims to:
152+
- Simplify IAB 2.x → 3.0 migration for the industry
153+
- Provide reliable, auditable mapping results
154+
- Support local-first processing for privacy
155+
- Enable extensibility through custom synonyms and overrides
156+
157+
When contributing, keep these goals in mind and consider how your changes support the broader industry adoption of IAB 3.0.
158+
159+
---
160+
161+
Thank you for contributing to the IAB Mapper! 🚀
13162

‎LICENSE‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,25 @@
1-
MIT License
1+
BSD 2-Clause License
22

33
Copyright (c) 2025 Mixpeek
44

5-
Permission is hereby granted, free of charge, to any person obtaining a copy
6-
of this software and associated documentation files (the "Software"), to deal
7-
in the Software without restriction, including without limitation the rights
8-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9-
copies of the Software, and to permit persons to whom the Software is
10-
furnished to do so, subject to the following conditions:
5+
Redistribution and use in source and binary forms, with or without
6+
modification, are permitted provided that the following conditions are met:
117

12-
The above copyright notice and this permission notice shall be included in all
13-
copies or substantial portions of the Software.
8+
1. Redistributions of source code must retain the above copyright notice, this
9+
list of conditions and the following disclaimer.
1410

15-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
11+
2. Redistributions in binary form must reproduce the above copyright notice,
12+
this list of conditions and the following disclaimer in the documentation
13+
and/or other materials provided with the distribution.
14+
15+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
19+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2225

‎README.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,38 @@
88
<a href="https://github.com/mixpeek/iab-mapper">View iab-mapper on GitHub</a>
99
•
1010
<a href="https://mixpeek.com/tools/iab-taxonomy-mapper">Open Mixpeek — IAB Taxonomy Mapper</a>
11+
•
12+
<a href="#-quick-start">Quick Start (5 min)</a>
1113
</p>
1214

1315
Map **IAB Content Taxonomy 2.x** labels/codes to **IAB 3.0** locally with a deterministic → fuzzy → (optional) semantic pipeline.
1416
Outputs are **IAB‑3.0–compatible IDs** for OpenRTB/VAST, with optional **vector attributes** (Channel, Type, Format, Language, Source, Environment) and **SCD** awareness.
1517

1618
> Local-first by default. No external APIs are required; LLM re‑rank is optional.
1719
20+
## 🎯 What it does
21+
22+
The IAB Mapper helps you migrate from IAB Content Taxonomy 2.x to 3.0 by:
23+
24+
1. **Input:** Your existing 2.x codes/labels (CSV or JSON)
25+
2. **Process:** Deterministic matching → fuzzy matching → optional semantic enhancement
26+
3. **Output:** Valid IAB 3.0 IDs ready for OpenRTB/VAST integration
27+
28+
**Example:**
29+
```bash
30+
# Input: 2.x codes
31+
"1-4","Sports"
32+
"2-12","Food & Drink"
33+
34+
# Output: 3.0 IDs
35+
"483","Sports"
36+
"3-5-2","Food & Drink > Cooking"
37+
```
38+
39+
Perfect for ad tech teams, content platforms, and anyone migrating to IAB 3.0.
40+
41+
> **💡 Try the official samples:** Use `demo/official_samples/sample_2x_codes_official.csv` for realistic testing with 60+ IAB categories.
42+
1843
---
1944

2045
## 📚 Table of Contents
@@ -205,6 +230,9 @@ iab-mapper sample_2x_codes.csv -o mapped.json
205230

206231
# enable local embeddings (improves recall on free‑text labels)
207232
iab-mapper sample_2x_codes.csv -o mapped.json --use-embeddings
233+
234+
# try with official IAB sample data (recommended)
235+
iab-mapper demo/official_samples/sample_2x_codes_official.csv -o mapped_official.json
208236
```
209237

210238
OpenRTB and VAST helpers (example output):
@@ -471,7 +499,17 @@ iab-mapper sample_2x_codes.csv -o mapped.json --use-embeddings --drop-scd --max-
471499
---
472500

473501
## 📜 License
474-
MIT. See [LICENSE](LICENSE).
502+
BSD 2-Clause. See [LICENSE](LICENSE).
475503

476504
Include IAB attribution in your deployed UI/footer:
477-
> “IAB is a registered trademark of the Interactive Advertising Bureau. This tool is an independent utility built by Mixpeek for interoperability with IAB Content Taxonomy standards.”
505+
> "IAB is a registered trademark of the Interactive Advertising Bureau. This tool is an independent utility built by Mixpeek for interoperability with IAB Content Taxonomy standards."
506+
507+
---
508+
509+
## 📞 Support & Contact
510+
511+
- **Issues:** [GitHub Issues](https://github.com/mixpeek/iab-mapper/issues)
512+
- **Documentation:** [Mixpeek IAB Mapper](https://mixpeek.com/tools/iab-taxonomy-mapper)
513+
- **Questions:** [Open an issue](https://github.com/mixpeek/iab-mapper/issues/new) or contact [Mixpeek](https://mixpeek.com)
514+
515+
For enterprise support, custom integrations, or questions about multimodal classification extensions, reach out to the Mixpeek team.

0 commit comments

Comments
 (0)