Merge pull request #46 from dhruvdcoder/improve-contrib-guide

Improve contribution docs, templates, and sync xlm-models versioning

Author: dhruvdcoder

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,23 +11,44 @@ assignees: ''
 A clear and concise description of what the bug is.
 
 **To Reproduce**
-Here is the minimal python script that reproduces the issue...
+Minimal repro: an `xlm` command or Python script.
 
+```bash
+# Example
+xlm job_type=train job_name=repro experiment=... debug=overfit
+```
+
+```python
+# Or minimal Python
+```
 
 **Expected behavior**
-A clear and concise description of what you expected to happen.
+What you expected to happen.
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**Actual behavior**
+What happened instead (traceback, wrong metrics, etc.).
+
+**Relevant config**
+Hydra experiment and overrides (paste or link):
+
+```yaml
+experiment=...
+# +overrides
+```
 
 **Environment**
- - OS: 
- - Pytorch version
- - Lightning version
- - Transformers version
- - Hydra version
 
+- OS:
+- Python:
+- xlm-core: <!-- python -c "import xlm; print(xlm.__version__)" -->
+- xlm-models (if applicable):
+- PyTorch:
+- Lightning:
+- Transformers:
+- Hydra:
 
+**Screenshots**
+If applicable.
 
 **Additional context**
-Add any other context about the problem here.
+Logs, checkpoint paths, or links to related issues.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -8,13 +8,22 @@ assignees: ''
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. 
+A clear and concise description of what the problem is.
+
+**Which component does this affect?**
+
+- [ ] Core framework (`src/xlm/`)
+- [ ] Maintained Model family (`xlm-models/` )
+- [ ] Task / dataset
+- [ ] CLI / commands
+- [ ] Documentation
+- [ ] Other
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
 **Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
+Any alternative solutions or features you've considered.
 
 **Additional context**
-Add any other context or screenshots about the feature request here.
+Links to similar features in other frameworks.

.github/ISSUE_TEMPLATE/new_model.md

@@ -0,0 +1,40 @@
+---
+name: New model
+about: Propose a new language model family for XLM
+title: "[Model] ..."
+labels: new-model
+assignees: ''
+
+---
+
+**Model name**
+<!-- Short name (e.g. `my_nar_lm`) -->
+
+**Paper / reference**
+<!-- arXiv link, OpenReview, project page, or brief description if no paper -->
+
+**Where will it live?**
+
+- [ ] Maintained in `xlm-models/` (this repo)
+- [ ] External repository (separate package)
+
+**Architecture summary**
+<!-- How does generation differ from existing families (ARLM, ILM, MDLM, MLM, …)? -->
+
+**Components**
+<!-- Which of the four pieces need non-standard behavior? -->
+
+- [ ] Model (forward pass)
+- [ ] Loss
+- [ ] Predictor
+- [ ] Collator / datamodule
+
+**Dependencies**
+<!-- Any new optional extras beyond core xlm-core? -->
+
+**Checkpoints**
+<!-- Are there existing checkpoints that your code will allow loading or will you be providing checkpoints for your model? -->
+
+- [ ] Existing checkpoints
+- [ ] New checkpoints
+

.github/ISSUE_TEMPLATE/new_task.md

@@ -0,0 +1,32 @@
+---
+name: New task or dataset
+about: Propose wiring a new dataset or benchmark into XLM
+title: "[Task] ..."
+labels: new-task
+assignees: ''
+
+---
+
+**Dataset name**
+
+**Source**
+<!-- Hugging Face Hub path (e.g. `namespace/dataset/split`), paper, or local path -->
+
+**Task type**
+
+- [ ] Language modeling (pretrain)
+- [ ] Seq2seq / instruction
+- [ ] Eval-only benchmark
+- [ ] Other (describe)
+
+**Model families**
+<!-- Which families should support this task initially? e.g. ARLM, ILM, FlexMDM -->
+
+**Preprocessing**
+<!-- Brief description of columns needed, filters, post-hoc evaluators -->
+
+**Optional dependencies**
+<!-- e.g. `xlm-core[safe]`, chemistry stack, math-verify -->
+
+**Additional context**
+<!-- Example rows, expected metrics, links to similar tasks in `src/xlm/tasks/` -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+## What
+
+<!-- 1–2 sentence summary of the change -->
+
+## Contribution type
+
+<!-- Check all that apply -->
+
+- [ ] Maintained model (`xlm-models/`)
+- [ ] External model (separate repo)
+- [ ] Task or dataset
+- [ ] Core framework (`src/xlm/`)
+- [ ] Documentation
+- [ ] Bug fix
+- [ ] Other (describe below)
+
+## Changes
+
+<!-- Bullet list of what changed -->
+
+-
+
+## Testing
+
+<!-- How you verified the change (commands, configs, screenshots) -->
+
+```bash
+# e.g. pytest -m "not slow and not cli"
+```
+
+## Documentation
+
+<!-- Docs added or updated; link to pages if applicable -->
+
+- [ ] No doc changes needed
+- [ ] Updated `docs/` and/or `mkdocs.yml`
+- [ ] Updated `CONTRIBUTING.md` or contributing guides
+
+## Related issues
+
+<!-- Link issues: Fixes #123, Closes #456 -->

.github/release.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
-"""Bump xlm-core version, push to main, and create a GitHub release.
+"""Bump xlm-core and xlm-models versions, push to main, and create a GitHub release.
 
 Used locally and from .github/workflows/release.yml. The release tag is always
 ``v`` + the version read from ``src/xlm/version.py`` after the bump, matching
-publish.yml / docs-release.yml.
+publish.yml / docs-release.yml. Both ``src/xlm/version.py`` and
+``xlm-models/version.py`` are updated to the same version.
 
 Examples:
     python .github/release.py 0.1.4
@@ -23,6 +24,8 @@
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 VERSION_PY = REPO_ROOT / "src" / "xlm" / "version.py"
+MODELS_VERSION_PY = REPO_ROOT / "xlm-models" / "version.py"
+VERSION_PY_PATHS = (VERSION_PY, MODELS_VERSION_PY)
 TAG_PREFIX = "v"
 
 _VERSION_ENV_KEYS = (
@@ -173,7 +176,10 @@ def require_clean_tree(dry_run: bool) -> None:
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
-        description="Bump version.py, push to main, and publish a GitHub release.",
+        description=(
+            "Bump version.py files for xlm-core and xlm-models, push to main, "
+            "and publish a GitHub release."
+        ),
     )
     parser.add_argument(
         "version",
@@ -246,16 +252,20 @@ def main(argv: list[str] | None = None) -> int:
 
     if not args.publish_only:
         require_clean_tree(args.dry_run)
-        write_version(target)
-        written = read_version()
-        if written != target.version:
-            raise RuntimeError(
-                f"version.py mismatch after write: expected {target.version}, got {written}"
-            )
-        print(f"Updated {VERSION_PY.relative_to(REPO_ROOT)}")
+        for path in VERSION_PY_PATHS:
+            write_version(target, path=path)
+            written = read_version(path)
+            if written != target.version:
+                raise RuntimeError(
+                    f"{path} mismatch after write: expected {target.version}, got {written}"
+                )
+            print(f"Updated {path.relative_to(REPO_ROOT)}")
 
         commit_msg = f"Release version {target.version}"
-        run(["git", "add", str(VERSION_PY.relative_to(REPO_ROOT))], dry_run=args.dry_run)
+        run(
+            ["git", "add", *[str(p.relative_to(REPO_ROOT)) for p in VERSION_PY_PATHS]],
+            dry_run=args.dry_run,
+        )
         run(["git", "commit", "-m", commit_msg], dry_run=args.dry_run)
 
         if not args.skip_push:
@@ -278,7 +288,10 @@ def main(argv: list[str] | None = None) -> int:
     if args.dry_run:
         print("Dry run complete; no changes were pushed and no release was created.")
     else:
-        print(f"Done. Published {target.tag} — PyPI/docs workflows run on release publish.")
+        print(
+            f"Done. Published {target.tag} — PyPI (xlm-core + xlm-models) and docs "
+            "workflows run on release publish."
+        )
     return 0
 
 

.github/workflows/publish.yml

@@ -14,11 +14,11 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
       with:
         ref: ${{ github.event.inputs.tag_name || github.event.release.tag_name }}
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies
@@ -47,7 +47,7 @@ jobs:
         echo "patch=$PATCH_NUM" >> $GITHUB_OUTPUT
         echo "suffix=$SUFFIX" >> $GITHUB_OUTPUT
         echo "Version extracted: $MAJOR.$MINOR.$PATCH_NUM$SUFFIX"
-    - name: Build and publish
+    - name: Build and publish xlm-core
       env:
         TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
         TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
@@ -57,4 +57,16 @@ jobs:
         XLM_CORE_VERSION_SUFFIX: ${{ steps.get_version.outputs.suffix }}
       run: |
         python setup.py sdist bdist_wheel
-        twine upload dist/*
+        twine upload dist/*
+    - name: Build and publish xlm-models
+      env:
+        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        XLM_CORE_VERSION_MAJOR: ${{ steps.get_version.outputs.major }}
+        XLM_CORE_VERSION_MINOR: ${{ steps.get_version.outputs.minor }}
+        XLM_CORE_VERSION_PATCH: ${{ steps.get_version.outputs.patch }}
+        XLM_CORE_VERSION_SUFFIX: ${{ steps.get_version.outputs.suffix }}
+      run: |
+        cd xlm-models
+        python setup.py sdist bdist_wheel
+        twine upload dist/*