Skip to content

Commit 3f27c40

Browse files
LucaBonaminoLucaBonamino
authored
Contribution templates (#5)
* PR request template * templates * roadmap
1 parent 924a083 commit 3f27c40

File tree

9 files changed

+401
-175
lines changed

9 files changed

+401
-175
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: Bug report
3+
about: Report a bug or unexpected behavior
4+
labels: bug
5+
---
6+
7+
## Summary
8+
9+
Briefly describe the problem.
10+
11+
## Reproduction steps
12+
13+
How can the issue be reproduced?
14+
15+
```rust
16+
// minimal example, if applicable
17+
```
18+
19+
## Expected vs actual behavior
20+
21+
What did you expect to happen, and what happened instead?
22+
23+
## Environment
24+
25+
- OS:
26+
- Rust version (```rustc --version```):
27+
- lin_algebra version:
28+
29+
## Additional context
30+
31+
Any other information that might help (logs, error messages, ideas).

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Feature request
3+
about: Suggest a new feature or improvement
4+
labels: enhancement
5+
---
6+
7+
## Summary
8+
9+
Briefly describe the feature or improvement you are proposing.
10+
11+
## Motivation
12+
13+
Why is this feature useful?
14+
What problem does it solve?
15+
16+
## Proposed usage (optional)
17+
18+
If you have an idea of how this feature could look in Python, show a short example.
19+
20+
```rust
21+
// example usage
22+
```
23+
24+
## Additional context
25+
26+
Any other information, references, or links that might be helpful.

‎.github/pull_request_template.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## Description
2+
3+
Briefly describe the changes in this pull request.
4+
5+
## Type of change
6+
7+
Please check the relevant option:
8+
9+
- [ ] Bug fix
10+
- [ ] New feature
11+
- [ ] Performance improvement
12+
- [ ] Documentation update
13+
- [ ] Refactor / cleanup
14+
15+
## Changes made
16+
17+
-
18+
-
19+
-
20+
21+
## Testing
22+
23+
Describe how you tested these changes:
24+
25+
- [ ] Existing tests pass
26+
- [ ] New tests added (if applicable)
27+
- [ ] Manual testing
28+
29+
## Checklist
30+
31+
- [ ] Code builds successfully
32+
- [ ] Public APIs are documented
33+
- [ ] Documentation updated (if needed)
34+
- [ ] No breaking changes (or clearly documented)
35+
36+
## Related issues
37+
38+
Closes # (if applicable)

‎CONTRIBUTING.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Contributing to lin_algebra
2+
3+
Thank you for your interest in contributing!
4+
5+
This project is open to:
6+
- bug fixes
7+
- performance improvements
8+
- documentation improvements
9+
- examples and tests
10+
11+
---
12+
13+
## How to contribute
14+
15+
1. Fork the repository
16+
2. Create a new branch from `main`
17+
3. Make your changes
18+
4. Open a Pull Request against `main`
19+
20+
Please keep pull requests focused and well-described.
21+
22+
---
23+
24+
## Development setup
25+
26+
```bash
27+
cargo build
28+
cargo test
29+
cargo fmt
30+
```
31+
32+
33+
## Code Style
34+
- Prefer clear names over clever code
35+
- Add documentation comments (///) for public items
36+
- Add tests for new functionality when possible
37+
38+
## Question or ideas?
39+
Feel free to open an issue to discuss changes before starting work.

‎README.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,4 +60,30 @@ fn main() {
6060
```
6161

6262
## License
63-
MIT
63+
MIT
64+
65+
## Python bindings
66+
67+
Python bindings are provided in the separate project
68+
[`gf2_lin_algebra`](https://github.com/LucaBonamino/gf2_lin_algebra).
69+
70+
They are intentionally limited to GF(2) and focus on performance and simplicity. The Rust crate `lin_algebra` is designed to be more general.
71+
72+
## Roadmap
73+
74+
This project is under active development, with a focus on both research and practical use.
75+
76+
Current and planned directions include:
77+
- improving the internal design of GF(2) matrices
78+
- adding optimized representations (e.g. bit-packed storage)
79+
- generalizing the Rust core to support linear algebra over arbitrary fields
80+
81+
The Python bindings (`gf2_lin_algebra`) are intentionally limited to GF(2), while the Rust crate (`lin_algebra`) aims to be more general.
82+
83+
For a detailed list of planned improvements and areas where help is welcome, see [ROADMAP.md](ROADMAP.md).
84+
85+
## Contributing
86+
87+
Contributions are welcome!
88+
89+
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

‎ROADMAP.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Roadmap
2+
3+
This project is research- and education-oriented, but there are several important improvements planned to make the codebase cleaner, faster, and more extensible.
4+
5+
Contributions and discussion are very welcome.
6+
7+
---
8+
9+
## 1. Decouple `GF2Matrix` from `Matrix<u8>`
10+
11+
Currently, `GF2Matrix` is closely tied to the generic `Matrix<u8>` type. Conceptually, this is not ideal: a matrix over GF(2) is a distinct mathematical object with different semantics and invariants.
12+
13+
Goals:
14+
- Make `GF2Matrix` a first-class type
15+
- Avoid treating `GF2Matrix` as an alias or thin wrapper over `Matrix<u8>`
16+
- Clarify invariants (entries are always in {0,1})
17+
- Improve API clarity and correctness
18+
- Prepare the codebase for alternative internal representations
19+
20+
This change is primarily architectural and should preserve existing functionality and behavior.
21+
22+
---
23+
24+
## 2. Optimized storage and processing for GF(2) matrices
25+
26+
Introduce a bit-packed representation for `GF2Matrix` to improve performance and memory efficiency.
27+
28+
Goals:
29+
- Add a bit-packed backend (e.g. using `u64` blocks)
30+
- Keep the current non-bit-packed representation for clarity,
31+
experimentation, and teaching
32+
- Allow both representations to coexist
33+
- Avoid premature optimization or loss of readability
34+
- Enable future performance comparisons and benchmarks
35+
36+
This project explicitly aims to remain suitable for research and education, so clarity and correctness are more important than maximal optimization.
37+
38+
---
39+
40+
## 3. Generalization to linear algebra over arbitrary fields
41+
42+
The long-term goal of `lin_algebra` is to support linear algebra over general fields, not only GF(2).
43+
44+
GF(2) currently serves as the primary reference case: it is simple, well-defined, and particularly relevant for cryptography and coding theory. Design decisions and abstractions will be validated on GF(2) before being generalized.
45+
46+
Goals:
47+
- Support linear algebra over arbitrary fields (e.g. GF(p), rationals)
48+
- Introduce field abstractions only when they are justified
49+
- Avoid over-engineering and unnecessary trait complexity
50+
- Keep the codebase readable and suitable for research and teaching
51+
- Allow experimentation with different field implementations
52+
53+
Generalization will be approached incrementally, starting from GF(2) and extending to other fields once the design is stable.
54+
55+
---
56+
57+
## Getting involved
58+
59+
If you are interested in working on any of these topics:
60+
- comment on an existing issue,
61+
- open a new issue to discuss design ideas,
62+
- or submit a draft pull request.
63+
64+
Even partial contributions, experiments, or design discussions are welcome.

0 commit comments

Comments
 (0)