Markdownlint pre-commit

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,16 +7,16 @@ assignees: jlamypoirier
 
 ---
 
-# 🐞 Describe the Bug
+## 🐞 Describe the Bug
 
 Provide a clear and concise description of the bug.
 
-# 🔄 Steps to Reproduce
+## 🔄 Steps to Reproduce
 
 Steps to reproduce the behavior:
 
-1. **Get the relevant Fast-LLM version** (e.g., git commit hash or Docker image tag) that you encountered the issue with.
-2. **Run the following command** (modify or redact as needed):
+1.  **Get the relevant Fast-LLM version** (e.g., git commit hash or Docker image tag) that you encountered the issue with.
+2.  **Run the following command** (modify or redact as needed):
 
     ```bash
     torchrun --rdzv_backend=static \
@@ -31,14 +31,14 @@ Steps to reproduce the behavior:
              --config /path/to/your/config.yaml
     ```
 
-3. **Include relevant log excerpts** to help us diagnose the issue, with `NCCL_DEBUG=INFO` (or higher) enabled. Make sure the logs contain the full configuration of the run.
-4. **Provide the configuration YAML** used for the Fast-LLM setup if logs are unavailable.
+3.  **Include relevant log excerpts** to help us diagnose the issue, with `NCCL_DEBUG=INFO` (or higher) enabled. Make sure the logs contain the full configuration of the run.
+4.  **Provide the configuration YAML** used for the Fast-LLM setup if logs are unavailable.
 
-# 🎯 Expected Behavior
+## 🎯 Expected Behavior
 
 Describe what you expected to happen.
 
-# 📜 Environment Information
+## 📜 Environment Information
 
 Run the following script in your environment and paste its output here:
 
@@ -105,10 +105,10 @@ fi
 echo "=== END OF ENVIRONMENT INFORMATION ==="
 ```
 
-# 📝 Additional Context
+## 📝 Additional Context
 
 Include any other information that may help us understand the issue, such as:
 
-- Recent changes to the configuration or code.
-- Whether the issue occurs consistently or intermittently.
-- Any troubleshooting steps you have already tried.
+-                     Recent changes to the configuration or code.
+-                     Whether the issue occurs consistently or intermittently.
+-                     Any troubleshooting steps you have already tried.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,27 +7,27 @@ assignees: ''
 
 ---
 
-# 🧐 Problem Description
+## 🧐 Problem Description
 
 Is your feature request related to a specific problem? Please describe it clearly.
 For example: "I'm always frustrated when [...]"
 
-# 💡 Proposed Solution
+## 💡 Proposed Solution
 
 Describe the solution you would like to see.
 Be as specific as possible about how it would work or be implemented.
 
-# 🔄 Alternatives Considered
+## 🔄 Alternatives Considered
 
 Have you considered any alternative solutions or approaches?
 If so, please describe them and explain why they might not be ideal.
 
-# 📈 Potential Benefits
+## 📈 Potential Benefits
 
 Explain how this feature could benefit Fast-LLM users.
 Consider how it might improve performance, usability, scalability, etc.
 
-# 📝 Additional Context
+## 📝 Additional Context
 
 Add any other context or information that could help us understand the feature request better.
 If applicable, provide links to relevant references or examples.

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,54 +9,54 @@ Closes # <!-- Insert issue number here, if applicable -->
 
 Select all that apply:
 
-- [ ] 🐛 **Bug fix** (non-breaking change that addresses a specific issue)
-- [ ] 🚀 **New feature** (non-breaking change that adds functionality)
-- [ ] ⚠️ **Breaking change** (a change that could affect existing functionality)
-- [ ] 📈 **Performance improvement/optimization** (improves speed, memory usage, or efficiency)
-- [ ] 🛠️ **Code refactor** (non-functional changes that improve code readability, structure, etc.)
-- [ ] 📦 **Dependency bump** (updates dependencies, including Dockerfile or package changes)
-- [ ] 📝 **Documentation change** (updates documentation, including new content or typo fixes)
-- [ ] 🔧 **Infrastructure/Build change** (affects build process, CI/CD, or dependencies)
+-                     [ ] 🐛 **Bug fix** (non-breaking change that addresses a specific issue)
+-                     [ ] 🚀 **New feature** (non-breaking change that adds functionality)
+-                     [ ] ⚠️ **Breaking change** (a change that could affect existing functionality)
+-                     [ ] 📈 **Performance improvement/optimization** (improves speed, memory usage, or efficiency)
+-                     [ ] 🛠️ **Code refactor** (non-functional changes that improve code readability, structure, etc.)
+-                     [ ] 📦 **Dependency bump** (updates dependencies, including Dockerfile or package changes)
+-                     [ ] 📝 **Documentation change** (updates documentation, including new content or typo fixes)
+-                     [ ] 🔧 **Infrastructure/Build change** (affects build process, CI/CD, or dependencies)
 
 ## 📝 Changes
 
 List the key changes introduced in this PR:
 
-1. Change A
-2. Change B
+1.                Change A
+2.                Change B
 
 ## ✅ Checklist
 
 Make sure the following tasks are completed before submitting the PR:
 
 ### General
 
-- [ ] 📜 I have read and followed the [contributing guidelines](https://servicenow.github.io/Fast-LLM/developers/contributing).
-- [ ] 🏷️ I am using a clear and descriptive PR title that summarizes the key change or feature introduced.
-- [ ] 🎉 The functionality is complete, and I have tested the changes.
-- [ ] 📝 I have updated the documentation if needed.
-- [ ] ⚠️ The change does not introduce any new issues (e.g., runtime warnings, type checker errors, linting problems, unhandled edge cases).
-- [ ] 🧩 I have commented my code, especially in hard-to-understand areas.
+-                     [ ] 📜 I have read and followed the [contributing guidelines](https://servicenow.github.io/Fast-LLM/developers/contributing).
+-                     [ ] 🏷️ I am using a clear and descriptive PR title that summarizes the key change or feature introduced.
+-                     [ ] 🎉 The functionality is complete, and I have tested the changes.
+-                     [ ] 📝 I have updated the documentation if needed.
+-                     [ ] ⚠️ The change does not introduce any new issues (e.g., runtime warnings, type checker errors, linting problems, unhandled edge cases).
+-                     [ ] 🧩 I have commented my code, especially in hard-to-understand areas.
 
 ### Dependencies and Configuration
 
-- [ ] 🐋 I have updated the Docker configuration or dependencies, if applicable.
-- [ ] 🔄 I have ensured compatibility with the existing setup after dependency changes.
+-                     [ ] 🐋 I have updated the Docker configuration or dependencies, if applicable.
+-                     [ ] 🔄 I have ensured compatibility with the existing setup after dependency changes.
 
 ### Testing
 
-- [ ] 🧪 I have added or updated tests to cover my changes.
-- [ ] ✔️ New and existing tests pass locally with my changes.
-- [ ] 🚦 I have tested these changes on GPUs and verified training stability.
-- [ ] 🏋️ I have tested the changes on realistic training workloads, if applicable.
+-                     [ ] 🧪 I have added or updated tests to cover my changes.
+-                     [ ] ✔️ New and existing tests pass locally with my changes.
+-                     [ ] 🚦 I have tested these changes on GPUs and verified training stability.
+-                     [ ] 🏋️ I have tested the changes on realistic training workloads, if applicable.
 
 ### Performance Impact
 
-- [ ] 📊 I have run benchmarks where applicable to evaluate the performance impact.
-- [ ] ✅ The benchmarks show no performance regression.
-- [ ] 🚀 The benchmarks indicate a potential performance improvement.
-- [ ] ⚠️ The benchmarks indicate a potential performance degradation.
-- [ ] 📈 I have provided benchmark results and detailed any performance impact below, if applicable.
+-                     [ ] 📊 I have run benchmarks where applicable to evaluate the performance impact.
+-                     [ ] ✅ The benchmarks show no performance regression.
+-                     [ ] 🚀 The benchmarks indicate a potential performance improvement.
+-                     [ ] ⚠️ The benchmarks indicate a potential performance degradation.
+-                     [ ] 📈 I have provided benchmark results and detailed any performance impact below, if applicable.
 
 ## 📊 Performance Impact Details
 

docs/.markdownlint.yaml → .markdownlint.yaml

@@ -20,13 +20,23 @@ MD010:
 # MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md013.md
 MD013: false
 
+# MD024/no-duplicate-heading Multiple headings with the same content (disabled because we do it).
+MD024: false
+
+# Temporarily disabled because not automatically fixed.
 # MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md030.md
-MD030:
+MD030: false
   # Spaces for single-line unordered list items
-  ul_single: 3
+  # ul_single: 3
   # Spaces for single-line ordered list items
-  ol_single: 2
+  # ol_single: 2
   # Spaces for multi-line unordered list items
-  ul_multi: 3
+  # ul_multi: 3
   # Spaces for multi-line ordered list items
-  ol_multi: 2
+  # ol_multi: 2
+
+# Code block style (disable because of interactions with mkdocs note blocks)
+MD046: false
+
+# Link and image reference definitions (disable because of interactions with mkdocs footnotes)
+MD053: false

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
@@ -11,7 +11,7 @@ repos:
         - --unsafe
     -   id: check-added-large-files
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.17.0
+    rev: v3.19.1
     hooks:
     -   id: pyupgrade
         args:
@@ -42,9 +42,18 @@ repos:
         name: isort (pyi)
         types: [pyi]
 -   repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
     -   id: black
         args:
             - "--config"
             - "./pyproject.toml"
+-   repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.16.0
+    hooks:
+    -   id: markdownlint-cli2
+        name: markdownlint
+        entry: markdownlint-cli2
+        args: ["--fix"]
+        language: node
+        types: [markdown]

CODE_OF_CONDUCT.md

@@ -6,36 +6,36 @@ This code of conduct provides guidelines for participation in ServiceNow-managed
 
 Communities thrive when members support each other and provide useful feedback.
 
-- Be polite and courteous. Respect and treat others as you would expect to be treated yourself.
-- Respect your audience. Posts should not upset, annoy, threaten, harass, abuse or embarrass other members.
-- User Contributions must not include material that is defamatory, obscene, indecent, abusive, offensive, harassing, violent, hateful, inflammatory or otherwise objectionable.
-- Lively and collegial discussions are always encouraged in a healthy community. It is okay to argue facts but not okay to argue personalities or personal beliefs.
-- Do not use text formats such as all caps or bold that may be read as annoying, rude or send a strong message.
-- Do not publish anyone's private personal information without their explicit consent.
-- Avoid using abbreviations or terminology that others may not understand. An abbreviation may mean something to you but in another context or country, it may have another meaning.
-- Be accountable for your actions by correcting your mistakes and indicating where you have changed a previous post of yours.
-- Mark content as correct and helpful, and provide feedback. If you read a discussion post that you find helpful, we encourage you to leave a positive vote and comment in the replies. If you find a post that is unhelpful, please provide more information in the issue comments.
+-                     Be polite and courteous. Respect and treat others as you would expect to be treated yourself.
+-                     Respect your audience. Posts should not upset, annoy, threaten, harass, abuse or embarrass other members.
+-                     User Contributions must not include material that is defamatory, obscene, indecent, abusive, offensive, harassing, violent, hateful, inflammatory or otherwise objectionable.
+-                     Lively and collegial discussions are always encouraged in a healthy community. It is okay to argue facts but not okay to argue personalities or personal beliefs.
+-                     Do not use text formats such as all caps or bold that may be read as annoying, rude or send a strong message.
+-                     Do not publish anyone's private personal information without their explicit consent.
+-                     Avoid using abbreviations or terminology that others may not understand. An abbreviation may mean something to you but in another context or country, it may have another meaning.
+-                     Be accountable for your actions by correcting your mistakes and indicating where you have changed a previous post of yours.
+-                     Mark content as correct and helpful, and provide feedback. If you read a discussion post that you find helpful, we encourage you to leave a positive vote and comment in the replies. If you find a post that is unhelpful, please provide more information in the issue comments.
 
 ## Issue board guidelines
 
 Many open-source projects provide an Issues board, with similar functionality to a Discussions forum. The same rules from the discussion forum guidelines apply to the Issues board.
 
 ServiceNow suggests the following technical support pathways for open-source projects:
 
-1. Clearly identify and document the issue or question you have.
-2. View the Documentation.
-3. Search the Discussions.
-4. Search the project documentation for known errors, useful solutions, and troubleshooting tips.
-5. Check the project contribution guidelines if you would like details on how you can submit a change. Community contributions are valued and appreciated!
-6. Log an Issue if it hasn't already been logged. If the issue has already been logged by another user, vote it up, and add a comment with additional or missing information. Do your best to choose the correct category when logging a new issue. This will make it easier to differentiate bugs from new feature requests or ideas. If after logging an issue you find the solution, please close your issue and provide a comment with the solution. This will help the project owners and other users.
-7. Contact the project team contributors of the project to see if they can help as a last resort only.
+1.                Clearly identify and document the issue or question you have.
+2.                View the Documentation.
+3.                Search the Discussions.
+4.                Search the project documentation for known errors, useful solutions, and troubleshooting tips.
+5.                Check the project contribution guidelines if you would like details on how you can submit a change. Community contributions are valued and appreciated!
+6.                Log an Issue if it hasn't already been logged. If the issue has already been logged by another user, vote it up, and add a comment with additional or missing information. Do your best to choose the correct category when logging a new issue. This will make it easier to differentiate bugs from new feature requests or ideas. If after logging an issue you find the solution, please close your issue and provide a comment with the solution. This will help the project owners and other users.
+7.                Contact the project team contributors of the project to see if they can help as a last resort only.
 
 ## Repositories
 
-- Read and follow the license instructions
-- Remember to include citations if you use someone else's work in your own project. Use the [`CITATION.cff`](CITATION.cff) to find the correct project citation reference.
-- ‘Star' project repos to save for future reference.
-- ‘Watch' project repos to get notifications of changes – this can get noisy for some projects, so only watch the ones you really need to track closely.
+-                     Read and follow the license instructions
+-                     Remember to include citations if you use someone else's work in your own project. Use the [`CITATION.cff`](CITATION.cff) to find the correct project citation reference.
+-                     ‘Star' project repos to save for future reference.
+-                     ‘Watch' project repos to get notifications of changes – this can get noisy for some projects, so only watch the ones you really need to track closely.
 
 ## Enforcement and reporting