Skip to content

docs: add CONTRIBUTING.md#407

Open
ANANYA542 wants to merge 6 commits intomllam:mainfrom
ANANYA542:docs/contributing-guide
Open

docs: add CONTRIBUTING.md#407
ANANYA542 wants to merge 6 commits intomllam:mainfrom
ANANYA542:docs/contributing-guide

Conversation

@ANANYA542
Copy link
Copy Markdown

@ANANYA542 ANANYA542 commented Mar 16, 2026

Describe your changes

Adds docs/contributing/contributing.md — a concise contributor guide that walks a new contributor through the full workflow from fork to merged PR.
Covers: ways to contribute, environment setup (referencing existing README install instructions rather than duplicating them), all 13 pre-commit hooks documented, code standards, how to run the test suite locally using the exact CI commands, PR checklist, review process with CHANGELOG format, and a troubleshooting table.
The goal is to give new contributors a single document to reference rather than piecing together information from the README, PR template, and CI config separately. Redundant sections have been removed and replaced with direct references to existing docs.

Issue Link

fixes #406

Type of change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • 📖 Documentation (Addition or improvements to documentation)

Checklist before requesting a review

  • My branch is up-to-date with the target branch - if not update your fork with the changes from the target branch (use pull with --rebase option if possible).
  • [X ] I have performed a self-review of my code
  • For any new/modified functions/classes I have added docstrings that clearly describe its purpose, expected inputs and returned values
  • I have placed in-line comments to clarify the intent of any hard-to-understand passages of my code
  • I have updated the README to cover introduced code changes
  • I have added tests that prove my fix is effective or that my feature works
  • I have given the PR a name that clearly describes the change, written in imperative form (context).
  • I have requested a reviewer and an assignee (assignee is responsible for merging). This applies only if you have write access to the repo, otherwise feel free to tag a maintainer to add a reviewer and assignee.

Checklist for reviewers

Each PR comes with its own improvements and flaws. The reviewer should check the following:

  • the code is readable
  • the code is well tested
  • the code is documented (including return types and parameters)
  • the code is easy to maintain

Author checklist after completed review

  • I have added a line to the CHANGELOG describing this change, in a section
    reflecting type of change (add section where missing):
    • added: when you have added new functionality
    • changed: when default behaviour of the code has been changed
    • fixes: when your contribution fixes a bug
    • maintenance: when your contribution is relates to repo maintenance, e.g. CI/CD or documentation

Checklist for assignee

  • PR is up to date with the base branch
  • the tests pass
  • (if the PR is not just maintenance/bugfix) the PR is assigned to the next milestone. If it is not, propose it for a future milestone.
  • author has added an entry to the changelog (and designated the change as added, changed, fixed or maintenance)
  • Once the PR is ready to be merged, squash commits and merge the PR.

ANANYA542 pushed a commit to ANANYA542/neural-lam that referenced this pull request Mar 19, 2026
…R template

- Move from docs/contributing/contributing.md to repo root CONTRIBUTING.md
- Replace full setup instructions with link to README
- Replace PR checklists with link to PR template
- Replace hook enumeration with link to .pre-commit-config.yaml
- Remove troubleshooting table and maintainer tags
- Add issue-first workflow and 'read discussion' step
- Keep only the two essential verify commands

Addresses feedback from @joeloskarsson on mllam#407
@sadamov
Copy link
Copy Markdown
Collaborator

sadamov commented Mar 31, 2026

@ANANYA542 I saw that you are expanding our work on this PR here. Note that autodoc is already tackled by #322. So I would prefer if this PR here could focus on the CONTRIBUTING.md file. And work closely together with #516 to reduce duplicated information that's hard to maintain. Could you reduce the scope of this PR here and update the title to make it clearer?

ANANYA542 and others added 4 commits April 2, 2026 14:39
…R template

- Move from docs/contributing/contributing.md to repo root CONTRIBUTING.md
- Replace full setup instructions with link to README
- Replace PR checklists with link to PR template
- Replace hook enumeration with link to .pre-commit-config.yaml
- Remove troubleshooting table and maintainer tags
- Add issue-first workflow and 'read discussion' step
- Keep only the two essential verify commands

Addresses feedback from @joeloskarsson on mllam#407
@ANANYA542 ANANYA542 force-pushed the docs/contributing-guide branch from 48462b1 to cecbf9f Compare April 2, 2026 09:28
@ANANYA542 ANANYA542 changed the title Docs/contributing guide docs: add CONTRIBUTING.md Apr 2, 2026
@ANANYA542
Copy link
Copy Markdown
Author

@sadamov Thanks for the review! I have dropped the Jupyter Book commits since #322 already tackles autodoc, and reduced the scope to focus solely on CONTRIBUTING.md at the root. This is ready and provides the complete contribution guidelines so that the subsequent #516 PR can heavily trim AGENTS.md to just link to this file. I updated the PR title as well.

@sadamov sadamov added the documentation Improvements or additions to documentation label Apr 13, 2026
@sadamov sadamov self-assigned this Apr 13, 2026
@sadamov sadamov self-requested a review April 17, 2026 19:33
Copy link
Copy Markdown
Collaborator

@sadamov sadamov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for your patience with the review. This past month has been crazy. The approach is good: concise, defers to existing docs rather than duplicating them, and links to authoritative sources.

Required changes

1. Missing CHANGELOG entry

The author checklist item is unchecked and no entry has been added to CHANGELOG.md. Required per project standards. Belongs under ### maintenance in the [unreleased] section, e.g.:

- Add `CONTRIBUTING.md` contributor guide [\#407](https://github.com/mllam/neural-lam/pull/407) @ANANYA542

2. Stale PR description

The description claims the file contains "all 13 pre-commit hooks documented" and "a troubleshooting table" — neither exists in the final file. Please update the PR description to match what was actually committed.

Follow-up items

AGENTS.md deduplication

AGENTS.md contains rules now fully covered by CONTRIBUTING.md:

  • PR rule 5: "Run pre-commit hooks locally"
  • PR rule 6: "Testing Mandate"
  • ### Changelog section

These should be stripped and replaced with a pointer to CONTRIBUTING.md at the top of ## Rules

README.md deduplication

README.md lines 570–578 ("Development and Contributing") now duplicates CONTRIBUTING.md.

Comment thread CONTRIBUTING.md
## Getting help

- Join the [mllam Slack workspace]( https://join.slack.com/t/ml-lam/shared_invite/zt-3jyw20n4g-ESRxMPPSijiZ2ZA6Nh8XhA)
- [Open a GitHub issue](https://github.com/mllam/neural-lam/issues)
Copy link
Copy Markdown
Collaborator

@sadamov sadamov Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace with short URL that is stable:

  • Join the [mllam Slack workspace](kutt.to/mllam)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOC] Add CONTRIBUTING.md to guide new contributors

2 participants