Repository navigation
Pull Request Guidelines
Propose · Implement · Validate · Review · Approve · Merge
A comprehensive guide to preparing, submitting, reviewing, approving, and merging high-quality contributions to EveryO.
Home · Contributing · Coding Standards · Testing and Quality Assurance
Project Maintainer: @krishanth7
Important
Repository Policy
Pull requests are evaluated for correctness, scope, maintainability, testing, documentation, security, and alignment with EveryO's technical direction.
Passing CI does not guarantee approval or merging.
This page documents existing repository policies and adds clearly identified recommendations for improving the review process.
- Overview
- Pull Request Lifecycle
- Before Opening a Pull Request
- Finding or Creating an Issue
- Fork and Branch Workflow
- Branch Naming
- Scope and Change Management
- Implementation Requirements
- Testing Requirements
- Numerical Verification
- Code Quality Checks
- Documentation Requirements
- Security Review
- Pull Request Template
- PR Title and Description
- Opening the Pull Request
- Continuous Integration
- Review Process
- Responding to Feedback
- Approval and Merge Decisions
- Merge Strategies
- Special Contribution Categories
- Maintainer Review Checklist
- Post-Merge Responsibilities
- Common Rejection Reasons
- Frequently Asked Questions
- Official References
- Next Steps
Pull requests are the primary mechanism for proposing changes to EveryO.
A pull request provides a structured record of the problem, implementation, testing, technical discussion, and final decision.
The review process aims to:
- Protect mathematical correctness.
- Preserve the framework's architecture.
- Maintain CPU-only functionality.
- Improve code quality.
- Prevent regressions.
- Support transparent collaboration.
- Keep project history understandable.
Contributions are welcome from:
- Developers.
- Researchers.
- Students.
- Educators.
- Technical writers.
- Software testers.
- Open-source contributors.
Repository write access is not required to submit a pull request from a fork.
Issue or Proposal
|
v
Scope Confirmation
|
v
Fork Repository
|
v
Create Branch
|
v
Implement Change
|
v
Add / Update Tests
|
v
Local Validation
|
v
Push to GitHub
|
v
Open Pull Request
|
v
Automated Checks
|
v
Maintainer Review
|
+-----+------+
| |
v v
Changes Needed Approved
| |
v v
Revise PR Merge Decision
| |
+----->------+
|
v
Merge / Close
| State | Meaning |
|---|---|
| Draft | Work is not ready for final review |
| Open | Contribution is awaiting checks or review |
| Changes requested | Revision is needed |
| Approved | Reviewer has accepted the proposed change |
| Merged | Change has entered the target branch |
| Closed | Pull request ended without merging |
Approval and merging are distinct actions.
- Read
CONTRIBUTING.md. - Review
REPOSITORY_RULES.md. - Review the Code of Conduct.
- Check existing issues and pull requests.
- Understand the relevant source code.
- Identify the expected behavior.
- Plan the necessary tests.
Search:
Large architectural changes should begin with an issue or GitHub Discussion.
Describe:
- The problem.
- Proposed design.
- Alternatives.
- Compatibility impact.
- Dependencies.
- Risks.
- Testing strategy.
Do not interpret the creation of a proposal as approval to merge its implementation.
Include:
- Affected version.
- Environment.
- Minimal reproduction.
- Expected behavior.
- Actual behavior.
- Relevant traceback.
Explain:
- User problem.
- Proposed functionality.
- API changes.
- Alternatives.
- Implementation scope.
- Testing requirements.
A pull request can reference an issue:
Closes #123Use the correct issue number.
GitHub can automatically close linked issues when qualifying pull requests merge into the repository's default branch.
Keep one main bug or proposal per issue.
Avoid combining unrelated changes into a single contribution.
Open:
https://github.com/krishanth7/EveryO
Select Fork.
git clone https://github.com/YOUR_USERNAME/EveryO.git
cd EveryOgit remote add upstream \
https://github.com/krishanth7/EveryO.gitgit fetch upstream
git switch main
git merge --ff-only upstream/maingit switch -c fix/dropout-scalinggit branch --show-currentAvoid implementing unrelated changes directly on the default branch.
The contribution guide recommends descriptive branch names.
fix/dropout-scaling
feature/new-activation
docs/improve-api-reference
test/autograd-regression
refactor/tensor-validation
perf/matmul-batching
- Keep names concise.
- Describe the change.
- Use lowercase where practical.
- Prefer hyphens between words.
- Avoid ambiguous names.
Branch prefixes such as fix/, feature/, and docs/ are appreciated but not enforced under the inspected contribution policy.
EveryO prioritizes focused, reviewable changes.
A focused pull request might:
- Correct one gradient bug.
- Add one neural network layer.
- Improve one documentation section.
- Add regression tests for a specific defect.
Avoid combining unrelated work such as:
- Rewriting the tensor engine.
- Changing the CLI.
- Reformatting the entire repository.
- Adding unrelated documentation.
- Modifying multiple independent APIs.
For substantial work, consider splitting it into independently reviewable pull requests.
Recommended sequence:
- Tests or groundwork.
- Core implementation.
- Integration.
- Documentation.
- Follow-up improvements.
This is a suggested approach, not a mandatory PR-count requirement.
EveryO's contribution policy establishes expectations for source changes.
Public functions and methods should include type hints.
Public modules, classes, and functions should include docstrings.
- Keep
everyo.coredependent only on NumPy. - Preserve CPU-only operation.
- Keep TensorFlow optional.
- Keep CUDA optional.
- Avoid mandatory network calls.
- Avoid API-key requirements.
Errors should identify relevant values.
Preferred:
EveryOShapeError:
Cannot multiply matrices with shapes
(32, 64) and (128, 10).
Avoid ambiguous exceptions without useful context.
Prefer:
- Small focused functions.
- Clear naming.
- Readable control flow.
- Limited dependencies.
- Documented assumptions.
Behavioral changes require appropriate tests.
python -m pytest -q./scripts/test.sh./scripts/test.sh --fast./scripts/test.sh --coverage| Change Type | Expected Testing |
|---|---|
| Bug fix | Regression test |
| Tensor operation | Forward and backward tests |
| Neural layer | Shape, gradient, serialization |
| Optimizer | Update correctness |
| Data pipeline | Alignment and edge cases |
| CUDA kernel | NumPy reference comparison |
| Serialization | Save/load round trip |
| Documentation | Example verification |
The full core test suite must pass without CUDA or TensorFlow installed.
Optional-component tests should skip cleanly when their prerequisites are unavailable.
Numerical correctness is especially important for EveryO.
For a scalar-valued function:
[ f(x) ]
the central finite-difference approximation is:
[ \frac{\partial f}{\partial x_i} \approx \frac{f(x_i+\epsilon)-f(x_i-\epsilon)} {2\epsilon} ]
New differentiable tensor operations must include finite-difference gradient checks under the current contribution guide.
import numpy as np
import everyo as eo
def test_square_gradient():
x = eo.tensor(
[2.0],
requires_grad=True,
)
y = x * x
y.backward()
np.testing.assert_allclose(
x.grad,
[4.0],
)Test:
- Broadcasting.
- Shape compatibility.
- Gradient accumulation.
- Extreme numerical values.
- Reused tensors.
- Invalid inputs.
EveryO uses Ruff.
ruff check .ruff format --check .ruff check . --fix
ruff format ../scripts/lint.shAutomatic fixes:
./scripts/lint.sh --fixThe repository rules call for compilation checks.
A suitable local check is:
python -m compileall -q everyoPassing lint and formatting checks does not establish mathematical correctness.
Changes to public behavior should include appropriate documentation updates.
README.md
CHANGELOG.md
docs/
GitHub Wiki
- Describe implemented behavior accurately.
- Use valid API signatures.
- Include executable examples where appropriate.
- Document limitations.
- Avoid unsupported performance claims.
Update:
CHANGELOG.md
Use the Unreleased section for relevant new changes.
Distinguish:
| Status | Meaning |
|---|---|
| Available | Implemented |
| Experimental | Implemented with limitations |
| Planned | Not implemented |
Never describe planned functionality as available.
Security is a required consideration for contributions.
EveryO's repository rules prohibit:
- Malicious code.
- Credential harvesting.
- Undisclosed network activity.
- Unauthorized telemetry.
- Incompatibly licensed code.
- Fabricated benchmarks or test results.
- Unreviewed generated bulk changes.
- No credentials committed.
- No private data included.
- No unauthorized network activity.
- External inputs validated.
- Serialization remains appropriately safe.
- Dependencies reviewed.
Do not disclose vulnerabilities publicly before coordinated disclosure.
Use:
GitHub Private Vulnerability Reporting
EveryO provides an existing pull request template.
Source: .github/PULL_REQUEST_TEMPLATE.md
The repository template includes:
## Summary
<!-- What does this change do, and why? -->
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Performance
- [ ] Refactor / internal cleanup
- [ ] Build, CI or tooling
## Testing
<!-- Which commands did you run, and what was the result? -->
## Checklist
- [ ] New behaviour is covered by tests, and the full suite passes on CPU.
- [ ] Ruff lint and formatting pass.
- [ ] Public APIs have type hints and docstrings.
- [ ] Core tests do not require optional backends or API keys.
- [ ] No credentials or private data are included.
- [ ] Documentation and changelog are updated where relevant.
- [ ] Planned features are not described as available.
## CUDA changes only
- [ ] Kernel results compared with NumPy.
- [ ] Bounds checking and CUDA error checking included.
- [ ] CPU path works without the extension.The above is a condensed representation of the existing template.
For complex changes, contributors may also include:
- Related issue.
- Design rationale.
- Alternatives considered.
- Compatibility impact.
- Benchmark methodology.
- Known limitations.
type(scope): concise description
Examples:
fix(autograd): correct broadcast gradient
feat(nn): add activation layer
test(core): expand numerical verification
docs(wiki): improve developer documentation
perf(data): reduce redundant allocations
This title format is recommended, not an enforced repository rule.
A good description answers:
- What problem does this solve?
- Why is the change necessary?
- How was it implemented?
- How was it tested?
- What could it affect?
## Summary
Fix incorrect gradient reduction for broadcast operands.
## Motivation
The existing backward calculation produces an incorrect
gradient shape for selected broadcast operations.
## Implementation
Update gradient reduction logic to account for
broadcast dimensions.
## Testing
- Added regression tests.
- Added finite-difference verification.
- Ran the CPU test suite.
- Ran Ruff checks.
## Compatibility
No intended public API changes.
## Related Issues
Closes #123Replace example issue numbers with actual repository references.
git add .Review staged changes before committing:
git diff --cachedgit commit -m "fix(autograd): correct broadcast gradient"git push -u origin fix/dropout-scalingUse your actual branch name consistently.
Select New pull request.
Confirm:
- Base repository:
krishanth7/EveryO. - Base branch:
main, unless otherwise instructed. - Head repository: your fork.
- Compare branch: your contribution branch.
Complete the template and create the pull request.
Use a draft pull request when the work is not ready for final review.
EveryO uses GitHub Actions.
The repository's CI includes:
- Python tests.
- Ruff linting.
- Formatting checks.
- TensorFlow integration.
- ONNX testing.
- Example execution.
- Package build validation.
After pushing:
- Open the PR's Checks tab.
- Inspect the running workflows.
- Review failed jobs.
- Reproduce failures locally.
- Push corrections.
- Confirm the checks rerun.
A workflow existing in the repository does not mean that the current PR passed it.
Check the actual workflow run.
Reviewers assess both technical correctness and project suitability.
| Criterion | Review Question |
|---|---|
| Correctness | Does the implementation work? |
| Mathematics | Are numerical results valid? |
| Architecture | Are boundaries respected? |
| Testing | Is behavior verified? |
| Compatibility | Are existing users affected? |
| Security | Are new risks introduced? |
| Documentation | Are changes explained? |
| Maintainability | Is the code understandable? |
Reviewers may:
- Approve.
- Comment.
- Request changes.
Maintainers may additionally decide to merge, defer, or close a pull request.
Feedback should be:
- Specific.
- Respectful.
- Actionable.
- Technically grounded.
- Focused on the contribution.
Review feedback is part of collaborative engineering.
- Read the comment carefully.
- Confirm the technical concern.
- Ask for clarification if necessary.
- Make the requested change or explain an alternative.
- Add tests when appropriate.
- Push the updated branch.
- Reply with a concise explanation.
Updated the gradient reduction logic and added
a finite-difference regression test.
The CPU test suite and Ruff checks were run locally.
Only report checks actually performed.
Review conversations should be resolved after the concern is addressed or an agreed decision is recorded.
Avoid marking unresolved technical concerns as completed.
EveryO's governance gives the maintainer final decision-making authority when consensus cannot be reached.
- Correct implementation.
- Appropriate tests.
- Acceptable architecture.
- Security review.
- Documentation quality.
- Project alignment.
The following are proposed controls:
| Gate | Recommended Condition |
|---|---|
| CI | Required checks pass |
| Review | At least one authorized approval |
| Conversations | Blocking concerns resolved |
| Security | No unresolved critical issues |
| Scope | Change remains focused |
| Documentation | Relevant updates complete |
These recommendations are not proof that corresponding GitHub branch protection rules are configured.
The maintainer may:
- Request revisions.
- Approve changes.
- Defer proposals.
- Squash commits.
- Close out-of-scope work.
- Reject technically unsuitable changes.
GitHub supports several merge strategies.
Preserves the branch's commits and adds a merge commit.
Combines the pull request's commits into one commit on the target branch.
Replays commits onto the target branch without a merge commit.
For small, focused changes, squash merging often produces a readable project history.
For substantial multi-commit changes, preserving individual commits may be useful.
The appropriate strategy remains a maintainer decision and depends on the repository's enabled merge settings.
Require:
- Forward correctness.
- Backward correctness.
- Finite-difference verification.
- Broadcasting tests.
- Edge-case validation.
Require:
- Correct module registration.
- Parameter handling.
- Forward behavior.
- Gradient tests.
- Serialization round trip.
Require:
- Bounds checking.
- CUDA error checking.
- Safe device-memory management.
- NumPy comparison.
- CPU fallback.
- Hardware disclosure.
Require reproducible evidence.
Recommended benchmark details:
- Hardware.
- Python version.
- Input shape.
- Dtype.
- Baseline timing.
- Modified timing.
- Repetitions.
- Correctness comparison.
Require accurate API references and correct examples.
Documentation-only changes may not need new runtime tests, but existing relevant checks should still be respected.
Sensitive vulnerability details must follow private disclosure procedures.
- Problem and scope are clear.
- Implementation is correct.
- Architecture is respected.
- Public APIs remain appropriate.
- Tests cover relevant behavior.
- Numerical results are verified.
- Lint passes.
- Formatting passes.
- CI results reviewed.
- Documentation updated.
- Compatibility impact assessed.
- No unnecessary dependencies introduced.
- No credentials included.
- No malicious behavior.
- No unauthorized telemetry.
- No unsafe input handling.
- No unsupported claims.
- Blocking concerns addressed.
- Authorized approval obtained where required.
- Merge strategy selected.
- Release implications understood.
Merging a pull request may require additional follow-up work.
- Confirm the merge.
- Review follow-up issues.
- Update related discussions when appropriate.
- Remove obsolete local branches.
After merging and updating your local main branch:
git switch main
git branch -d fix/dropout-scalingFor a branch in your fork:
git push origin --delete fix/dropout-scalingUse the actual branch name.
Depending on the change:
- Confirm issue closure.
- Update release notes.
- Monitor regressions.
- Record follow-up work.
- Include the change in an appropriate release.
A pull request may be rejected or closed for several reasons.
- Incorrect mathematical behavior.
- Missing regression tests.
- Unsupported architectural changes.
- Broken CPU compatibility.
- Unnecessary dependencies.
- Poor maintainability.
- Unrelated changes combined.
- Incomplete description.
- Unresolved review feedback.
- Significant unapproved scope expansion.
- Repeated failure to follow repository policies.
- Malicious code.
- Credential harvesting.
- Incompatible licensing.
- Fabricated results.
- Undisclosed network activity.
- Unreviewed generated bulk changes.
A pull request may be closed because it is:
- Duplicated.
- Superseded.
- No longer required.
- Deferred.
- Out of scope.
Maintainers should provide context where practical.
Can I submit a pull request without repository write access?
Yes. Fork EveryO, push your changes to your fork, and open a pull request.
Must every pull request have an issue?
The repository supports bounded improvements through issues or pull requests. Large architectural changes should begin with a discussion or design issue.
Can I submit a documentation-only pull request?
Yes. Documentation improvements are welcome.
Do I need CUDA hardware?
Not for ordinary CPU contributions. CUDA-specific changes require appropriate validation and honest disclosure of the hardware used.
Does passing CI guarantee merge approval?
No. Maintainers also evaluate correctness, maintainability, security, scope, and project direction.
Can I submit AI-generated code?
The repository prohibits unreviewed and unvalidated generated bulk changes. Contributors remain responsible for understanding, reviewing, testing, and validating everything they submit.
Who makes the final merge decision?
The project maintainer has final authority under the repository's governance policy.
| Resource | Link |
|---|---|
| EveryO Repository | GitHub |
| Pull Requests | Open Pull Requests |
| Pull Request Template | PULL_REQUEST_TEMPLATE.md |
| Contribution Guide | CONTRIBUTING.md |
| Repository Rules | REPOSITORY_RULES.md |
| Governance | GOVERNANCE.md |
| Code of Conduct | CODE_OF_CONDUCT.md |
| Security Policy | SECURITY.md |
| CI Workflow | tests.yml |
| Project Configuration | pyproject.toml |
| Changelog | CHANGELOG.md |
| GitHub Actions | Workflow Runs |
Continue with EveryO's engineering and governance documentation.
| Page | Focus |
|---|---|
| Release Process | Versioning, packaging, publishing, and release approval |
| Coding Standards | Source conventions and maintainability |
| Contributing | Contributor onboarding |
| Testing and Quality Assurance | Automated validation |
| Development Setup | Local environment configuration |
Wiki links become active after the corresponding pages are created.
Next Recommended Page: Release Process →
Home · Contributing · Coding Standards
EveryO — Open Machine Learning. Built for Developers.
Project Maintainer: @krishanth7
Open Source · MIT Licensed · Community Driven
© 2026 EveryO Contributors