1. Welcome
2. Project Philosophy
3. Ways to Contribute
4. Getting Started
5. Finding an Issue
6. Reporting Bugs
7. Proposing Features
8. Forking and Branching
9. Development Standards
10. Adding Tensor Operations
11. Adding Neural Network Layers
12. Contributing to CUDA
13. Testing Requirements
14. Code Style and Documentation
15. Commit Guidelines
16. Pull Request Workflow
17. Code Review Process
18. Continuous Integration
19. Community Standards
20. Security Reporting
21. Licensing and Intellectual Property
22. Project Governance
23. Maintainer Responsibilities
24. First Contribution Walkthrough
25. Contributor Checklist
26. Frequently Asked Questions
27. Official References
28. Next Steps

Thank you for your interest in contributing to EveryO.

EveryO is an open-source neural computing framework built around readable implementations of tensor computation, automatic differentiation, neural network modules, optimization, and model training.

The project aims to make machine learning internals understandable, testable, and reproducible.

Contributors may include:

• Python developers.
• Machine learning engineers.
• Research engineers.
• CUDA developers.
• Technical writers.
• Students and educators.
• Software testers.
• Open-source maintainers.

There is no minimum experience requirement for participation.

New contributors are encouraged to begin with focused improvements such as documentation corrections, reproducible bug reports, examples, and unit tests.

More complex changes may require familiarity with numerical computing, automatic differentiation, and EveryO's architecture.

EveryO prioritizes clarity, correctness, and reproducibility.

The core framework must not require:

• API keys.
• External AI services.
• Network calls during core execution.
• CUDA hardware.
• TensorFlow.

Optional integrations must not make the core installation unusable.

Performance improvements are welcome, but they should not unnecessarily sacrifice readability or mathematical correctness.

When an optimization introduces complexity, contributors should explain the benefit, demonstrate correctness, and provide measurable evidence.

You can contribute without writing new framework code.

For first-time contributors:

1. Improve unclear documentation.
2. Add a missing test.
3. Reproduce an existing bug.
4. Improve error messages.
5. Fix a narrowly scoped issue.

For experienced contributors:

1. Implement differentiable operations.
2. Add neural network layers.
3. Improve numerical stability.
4. Extend optional backend support.
5. Strengthen serialization or testing.

git clone https://github.com/krishanth7/EveryO.git

cd EveryO

python -m venv .venv

Activate on Linux or macOS:

source .venv/bin/activate

Activate on Windows PowerShell:

.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip

python -m pip install -e ".[dev]"

python -m everyo info

python -m everyo doctor

python -m pytest -q

ruff check .

ruff format --check .

Detailed instructions: Development Setup

The GitHub issue tracker is the primary location for reporting and discussing bounded technical work.

Browse EveryO Issues

• Read the issue description.
• Check whether a solution is already proposed.
• Review related pull requests.
• Confirm the expected behavior.
• Identify relevant source files.
• Ask focused questions when requirements are unclear.

GitHub labels, when present, can help contributors find suitable work.

Common open-source label conventions include:

These are common label conventions; availability should be checked in the EveryO repository.

Comment on an issue to communicate your intention to contribute when coordination would help.

An issue comment does not automatically grant exclusive ownership.

High-quality bug reports help maintainers reproduce and fix problems.

Include:

• EveryO version.
• Python version.
• Operating system.
• Relevant backend.
• Minimal reproduction.
• Expected behavior.
• Actual behavior.
• Complete relevant traceback.

python -m everyo info

## Summary

Tensor broadcasting produces an unexpected gradient.

## Environment

- EveryO version:
- Python version:
- Operating system:
- Backend:

## Steps to Reproduce

1. Create the tensors.
2. Execute the operation.
3. Call backward().
4. Inspect the gradient.

## Expected Behavior

Describe the mathematically expected gradient.

## Actual Behavior

Describe the observed result.

## Minimal Reproduction

```python
import everyo as eo

# Add a minimal reproducible example.

Include relevant error messages or numerical comparisons.

## 6.4 Bug Report Quality

Prefer the smallest example that demonstrates the problem.

Avoid attaching confidential datasets or private information.

> [!CAUTION]
> Security vulnerabilities must not be disclosed through public bug reports. Follow the private reporting process in [SECURITY.md](https://github.com/krishanth7/EveryO/blob/main/SECURITY.md).

---

# 7. Proposing Features

Feature proposals should explain both the desired capability and its value to EveryO.

## 7.1 Proposal Requirements

Describe:

1. The problem.
2. The proposed feature.
3. Intended users.
4. Public API implications.
5. Implementation approach.
6. Alternatives.
7. Dependencies.
8. Testing requirements.
9. Compatibility considerations.

## 7.2 Example Proposal

```markdown
## Feature Proposal

### Problem

Describe the limitation.

### Proposed Solution

Describe the new functionality.

### Example API

Provide a proposed usage example.

### Alternatives

Describe other approaches considered.

### Compatibility

Explain any API or dependency impacts.

### Validation

Describe how correctness will be tested.

Substantial architectural changes should begin with a GitHub Discussion or design issue, consistent with EveryO's governance process.

Do not assume that a proposed feature has been approved merely because an issue exists.

External contributors should normally work through forks and pull requests.

Open:

https://github.com/krishanth7/EveryO

Select Fork.

git clone https://github.com/YOUR_USERNAME/EveryO.git

cd EveryO

git remote add upstream \
  https://github.com/krishanth7/EveryO.git

git fetch upstream

git switch main

git merge --ff-only upstream/main

git switch -c fix/gradient-broadcasting

fix/gradient-broadcasting
feature/new-layer
docs/improve-installation
test/autograd-edge-cases
refactor/tensor-validation

Branch naming conventions are recommended rather than mandatory.

EveryO's contribution standards emphasize understandable code and testable behavior.

Public functions and methods should include type hints.

Public modules, classes, and functions should include meaningful docstrings.

Prefer small modules with clear responsibilities.

Avoid unrelated functionality inside a single module.

Errors should explain what went wrong.

Prefer:

EveryOShapeError:
Cannot multiply matrices with shapes
(32, 64) and (128, 10).

Over:

IndexError

Avoid adding dependencies to the core layer beyond NumPy.

New optional integrations should be isolated appropriately.

Changes to public APIs should be documented and tested.

Breaking changes require explicit review and appropriate release planning.

New tensor operations require mathematical verification.

everyo/core/operations.py

1. Implement the forward operation.
2. Implement the backward function.
3. Handle broadcasting.
4. Verify input and output shapes.
5. Add finite-difference gradient tests.
6. Export the operation publicly.
7. Document its behavior.

For scalar-valued (f):

[ \frac{\partial f}{\partial x_i} \approx \frac{f(x_i+\epsilon)-f(x_i-\epsilon)} {2\epsilon} ]

Test:

• Known numerical values.
• Gradient correctness.
• Shape compatibility.
• Broadcasting.
• Invalid inputs.
• Edge cases.

Finite-difference testing is a required part of EveryO's existing contribution guidance for differentiable operations.

New layers should integrate with EveryO's module architecture.

from everyo.nn import Module

from everyo.nn.module import register_module

A new layer should:

• Implement forward().
• Register parameters correctly.
• Support applicable gradient propagation.
• Provide configuration for serialization.
• Respect training/evaluation behavior.
• Include tests.

Layers with constructor arguments should implement get_config() when required for reconstruction.

Update:

everyo/nn/__init__.py
everyo/__init__.py

Include a model save/load round-trip test for serializable layers.

CUDA contributions require careful memory-safety and correctness validation.

cuda/src/
cuda/include/everyo_cuda.h
cuda/bindings/bindings.cpp
everyo/cuda/interface.py

• Validate memory bounds.
• Check CUDA calls.
• Check kernel launches.
• Use safe device-memory ownership.
• Provide CPU fallback behavior.
• Compare results against NumPy.

The repository's contribution guide requires appropriate use of:

EVERYO_CUDA_CHECK(...)

and:

EVERYO_CUDA_CHECK_KERNEL()

./scripts/build_cuda.sh

python -m pytest tests/test_devices.py -v

CUDA pull requests should specify the GPU and environment used for testing.

Do not claim CUDA execution was validated if the change was tested only on CPU.

Tests are essential for maintaining EveryO's mathematical correctness.

python -m pytest -q

python -m pytest tests/test_autograd.py -v

python -m pytest -m "not slow"

python -m pytest \
  --cov=everyo \
  --cov-report=term-missing

The core test suite must work without requiring TensorFlow or CUDA.

Optional backend tests should skip appropriately when dependencies or hardware are unavailable.

EveryO uses Ruff.

ruff check .

ruff format --check .

ruff format .

• Use accurate API names.
• Explain function parameters.
• Include meaningful examples.
• Document limitations.
• Avoid unsupported performance claims.
• Update the changelog for relevant changes.

Update the appropriate section of:

CHANGELOG.md

New unreleased changes should be recorded under the project's Unreleased section.

Clear commits simplify code review and project history.

type(scope): short description

feat(nn): add new activation layer

fix(autograd): correct broadcast gradient

test(core): add numerical gradient coverage

docs(wiki): improve contribution guide

perf(data): reduce unnecessary array copies

• Keep commits focused.
• Explain the purpose of changes.
• Avoid committing generated files unnecessarily.
• Do not include secrets.
• Separate unrelated modifications.

These are recommended conventions, not an enforced commit-message policy.

Pull requests are the primary mechanism for submitting code changes.

Fork Repository
       |
       v
Create Branch
       |
       v
Implement Change
       |
       v
Add Tests
       |
       v
Run Quality Checks
       |
       v
Push Branch
       |
       v
Open Pull Request
       |
       v
Maintainer Review
       |
       v
Revision if Needed
       |
       v
Merge or Close

git push -u origin fix/gradient-broadcasting

Visit:

EveryO Pull Requests

Select New pull request and choose the appropriate source and target branches.

The existing repository template requests:

• Summary.
• Type of change.
• Testing performed.
• Checklist completion.
• CUDA-specific validation where applicable.

## Summary

Describe what changed and why.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Performance
- [ ] Refactor
- [ ] CI or tooling

## Implementation

Describe the technical changes.

## Testing

List commands executed and results.

## Compatibility

Describe public API or behavioral impacts.

## Related Issues

Closes #ISSUE_NUMBER

Code review protects correctness and maintainability.

• Respond respectfully to feedback.
• Explain technical decisions.
• Resolve actionable concerns.
• Update tests when needed.
• Avoid unrelated changes during review.

A pull request may be:

• Approved.
• Returned for changes.
• Deferred.
• Closed without merging.
• Merged after approval.

A submitted pull request does not guarantee acceptance.

EveryO uses GitHub Actions for automated validation.

View CI Workflow

• Python compatibility.
• Unit and integration tests.
• Ruff linting.
• Formatting.
• TensorFlow integration.
• ONNX testing.
• Example execution.
• Package build checks.

Before requesting merge:

1. Check workflow results.
2. Review failures.
3. Reproduce issues locally.
4. Correct the problem.
5. Push updates.
6. Confirm checks rerun.

View GitHub Actions

CI status must be checked directly; this document does not assert that any particular workflow run has passed.

EveryO follows a published Code of Conduct.

• Respect other contributors.
• Welcome different experience levels.
• Provide constructive feedback.
• Focus on technical issues.
• Respect privacy.
• Communicate professionally.

• Harassment.
• Personal attacks.
• Discrimination.
• Publishing private information.
• Sustained disruption.
• Unwelcome sexual attention.
• Abusive conduct.

Follow the procedures described in:

CODE_OF_CONDUCT.md

Sensitive matters should be communicated privately to maintainers.

Security vulnerabilities require coordinated disclosure.

Do not publish exploit details in public issues or pull requests before coordinated disclosure.

Use:

Report a Vulnerability

• Affected EveryO version.
• Python version.
• Operating system.
• Vulnerability description.
• Reproduction steps.
• Potential impact.
• Proposed mitigation, if available.

The repository's security policy states:

These are volunteer-project targets, not contractual guarantees.

• Never commit credentials.
• Avoid unsafe deserialization.
• Validate untrusted inputs.
• Report memory-safety issues.
• Keep security discussions private until coordinated disclosure.

EveryO is distributed under the MIT License.

By submitting a contribution, contributors represent that they have the right to submit it and agree that it may be distributed under the repository's MIT License.

• Proprietary code without authorization.
• Confidential business information.
• Trade secrets.
• Private datasets.
• Credentials.
• Incompatibly licensed material.

Third-party code, datasets, models, and tools remain subject to their own licenses.

The MIT License does not authorize contributors or forks to imply official endorsement by EveryO or its maintainer.

References:

• LICENSE
• PROJECT_POLICY.md

EveryO is an independently maintained open-source project.

@krishanth7

The project prefers transparent technical discussions.

For substantial changes:

1. Explain the problem.
2. Discuss alternatives.
3. Evaluate compatibility.
4. Record trade-offs.
5. Seek practical consensus.
6. Obtain maintainer approval.

Contributing does not automatically grant:

• Repository write access.
• Administrative access.
• Release permissions.
• Maintainer status.

GOVERNANCE.md

Maintainers are responsible for protecting the project's technical integrity and community standards.

• Review contributions.
• Evaluate technical correctness.
• Maintain project direction.
• Enforce policies.
• Manage releases.
• Coordinate security responses.
• Document important decisions.

Recommended priorities include:

1. Security and correctness defects.
2. Regressions.
3. Compatibility problems.
4. Documentation inaccuracies.
5. Approved improvements.
6. Experimental proposals.

These priorities are recommendations rather than a published response-time guarantee.

Significant decisions should be explained through issues, pull requests, or project documentation where appropriate.

This example demonstrates a typical documentation contribution.

Fork the EveryO repository on GitHub.

git clone https://github.com/YOUR_USERNAME/EveryO.git

cd EveryO

git switch -c docs/improve-getting-started

Edit the relevant documentation.

python -m pytest -q

ruff check .

ruff format --check .

git add docs/

git commit -m "docs: improve getting started guide"

git push -u origin docs/improve-getting-started

Describe the change and include the validation performed.

Address feedback and update the branch as required.

• Read the contribution guide.
• Review the Code of Conduct.
• Understand the relevant issue.
• Set up the development environment.
• Create a focused branch.

• Follow coding conventions.
• Preserve core architectural principles.
• Add appropriate tests.
• Verify numerical correctness.
• Update documentation.
• Avoid unrelated modifications.

• Relevant tests pass locally.
• Full CPU test suite passes.
• Ruff lint passes.
• Ruff formatting passes.
• No secrets are included.
• Changelog updated where relevant.
• PR description is complete.

• Respond to comments.
• Explain technical trade-offs.
• Resolve requested changes.
• Recheck CI after updates.

Continue with the contributor and repository governance documentation.

Wiki links become active after the corresponding pages are created.