Welcome! This is the shared contribution guide for all PyAutoLabs repositories: scientific libraries, workspaces, tutorials, assistants, and development tools.
If you arrived from PyAutoFit, PyAutoGalaxy, PyAutoLens, PyAutoArray, or another repository, you are in the right place. You do not need to install PyAutoScientist or use AI to contribute. Questions, scientific examples, documentation, bug reports, tests, and conventional pull requests are welcome.
Questions, help with your code or your analysis, and ideas: the PyAutoLabs Discussions. Bug reports with a reproducer (a snippet, the traceback, your versions): an issue on the library's tracker. The Slack is for collaborators, by invitation.
The shared discussion categories are:
- Help & Questions: installation, using the software, and scientific or analysis questions.
- Ideas & Proposals: feature suggestions and concrete implementation proposals.
- Bugs & Errors: unexpected behaviour or an error that needs investigation.
- Announcements: maintainer news and releases.
- Show and tell: results, examples, and projects to share.
Mention the repository or package you are using. Search existing discussions and issues first. For substantial changes, discuss the approach before investing in implementation. A plain-English explanation is enough to begin; example code and links to relevant methods help.
Once a proposal is agreed or a defect is reproducible, create or link an implementation issue in the repository that owns the change. Keep the discussion and issue linked so the original context is not lost. Where available, mark a helpful resolution or settled proposal verdict as the accepted answer.
Use the affected repository's issue tracker for confirmed reproducible defects, not the PyAutoScientist tracker unless the problem is with PyAutoScientist itself. Include:
- a minimal runnable example and any small, shareable input needed to reproduce it;
- the full traceback or incorrect output;
- expected versus actual behaviour;
- operating system, Python version, and relevant package versions.
If you are unsure whether it is a bug, start in Bugs & Errors. Never post secrets, private data, or collaborator-controlled material publicly. For security-sensitive reports, follow the affected repository's security policy instead of opening a public discussion. If no private reporting route is listed, email James Nightingale at James.Nightingale@newcastle.ac.uk to arrange one; do not include sensitive details in the initial message.
Contributions with or without AI assistance are assessed against the same scientific, testing, and documentation standards.
- Read the target repository's README, contribution instructions, and AGENTS.md where present. Local setup, architecture, and validation requirements still apply.
- For a non-trivial change, agree the scope in Discussions and link the resulting repository issue.
- Fork the relevant repository or use an authorized branch. Keep the pull request focused.
- Add or update tests, examples, and documentation appropriate to the change.
- Open a pull request explaining what changed, why, the evidence that it works, and any downstream impact. Link its issue and originating discussion.
Maintainers may use automation or agents to assist triage and review. Humans remain responsible for contributor communication, consequential decisions, and accepting changes. No contribution is accepted merely because generated code runs or looks plausible.
For source libraries, install from source and run the documented tests. Describe changes to public APIs and effects on downstream libraries or workspaces.
For workspaces and tutorials, preserve scientific intent and teaching context. Where notebooks are generated, edit the source scripts and regenerate notebooks through the repository's documented process rather than hand-editing generated notebooks.
Workspace-test repositories are integration suites, not tutorials. Never weaken or remove checks to conceal a regression.
Validation should match the risk: unit tests for components, runnable examples and smoke tests for user workflows, integration tests across packages, and scientific comparisons where numerical behaviour changes. Repository guidance and release-readiness checks determine the applicable gates.
Be able to explain the intended behaviour, scientific assumptions, important decisions, and how correctness was checked. Document API changes and their downstream effects. Check the provenance and licence of adapted code, and cite published methods and existing software where appropriate.
AI-assisted work must follow the shared PyAuto AI Policy, including its requirements for expertise, validation, attribution, privacy, and human responsibility. Do not send private or embargoed information to an AI service without appropriate authorization.
PyAutoScientist is James Nightingale's experimental, human-led AI development ecosystem. It is optional: neither using the scientific libraries nor contributing to them requires adopting it.
If you want to explore its workflows, read its adoption guide and discuss setup with the maintainer. Its own README and organ-specific instructions describe development inside that ecosystem.
Participation is governed by the PyAutoLabs Code of Conduct. Use its private reporting contact for conduct concerns, not a public issue.
This guide, the Code of Conduct, and support guidance are maintained in PyAutoLabs/.github. GitHub displays supported defaults for repositories without a local override; these files are not automatically copied into repository clones or distributions.