Skip to content

Commit 8d6bc42

Browse files
VarnasrVarnasr
committed
Update README with honest status, OpenStacks branding, and improved governance docs
1 parent 1a68627 commit 8d6bc42

4 files changed

Lines changed: 169 additions & 121 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Code of Conduct
2+
3+
## Our Commitment
4+
5+
OpenStacks for Change is built for public interest work. We are committed to providing a welcoming, inclusive, and harassment-free experience for everyone — regardless of gender identity, sexual orientation, disability, ethnicity, religion, age, nationality, caste, class, or level of technical experience.
6+
7+
## Expected Behaviour
8+
9+
- **Be respectful and professional** in all interactions
10+
- **Be constructive** — offer feedback that helps improve the work
11+
- **Be inclusive** — use welcoming and gender-neutral language
12+
- **Be collaborative** — share knowledge generously and credit others' contributions
13+
- **Be honest** — about limitations, uncertainties, and the state of your work
14+
- **Respect privacy** — never share others' personal information or data
15+
16+
## Unacceptable Behaviour
17+
18+
- Harassment, intimidation, or discrimination of any kind
19+
- Sexualised language or imagery in any project space
20+
- Personal attacks, trolling, or deliberately inflammatory comments
21+
- Publishing others' private information without consent
22+
- Sustained disruption of discussions or project activities
23+
- Any conduct that would be considered inappropriate in a professional setting
24+
25+
## Scope
26+
27+
This code of conduct applies to all OpenStacks project spaces — including GitHub repositories, issues, pull requests, discussions, and any other communication channels associated with the project.
28+
29+
## Reporting
30+
31+
If you experience or witness unacceptable behaviour, please report it by emailing **varna.sr@gmail.com**. All reports will be handled confidentially.
32+
33+
## Enforcement
34+
35+
Project maintainers who do not follow or enforce this Code of Conduct may face temporary or permanent consequences as determined by the project leadership.
36+
37+
## Attribution
38+
39+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

‎CONTRIBUTING.md‎

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,72 @@
1-
# Contributing
1+
# Contributing to OpenStacks
22

3-
Contributions are welcome! Please read the guidelines.
3+
Thank you for your interest in contributing to [OpenStacks for Change](https://openstacks.dev). This guide applies to all repositories in the ecosystem.
4+
5+
## Who Can Contribute
6+
7+
OpenStacks welcomes contributions from:
8+
9+
- **Development practitioners** — Share tools, templates, and workflows from your own work (anonymised)
10+
- **Researchers and evaluators** — Contribute analysis scripts, methodologies, and replication files
11+
- **Data analysts and engineers** — Improve code quality, add tests, fix bugs
12+
- **Writers and editors** — Improve documentation, add use case guides, fix errors
13+
- **Students** — Practice with real-world development data and contribute improvements
14+
15+
## How to Contribute
16+
17+
### Reporting Issues
18+
19+
- Use the repository's **Issues** tab to report bugs, suggest features, or ask questions
20+
- Check existing issues first to avoid duplicates
21+
- Use issue templates where available
22+
23+
### Submitting Changes
24+
25+
1. **Fork** the repository
26+
2. **Create a branch** for your change (`git checkout -b feature/your-feature-name`)
27+
3. **Make your changes** with clear, descriptive commit messages
28+
4. **Test your changes** — ensure scripts run and notebooks execute without errors
29+
5. **Submit a pull request** with a clear description of what you changed and why
30+
31+
### What Makes a Good Contribution
32+
33+
- **Self-contained** — Scripts should work independently with sample data
34+
- **Documented** — Include comments, a header description, and usage instructions
35+
- **Anonymised** — Never include real participant data, names, or identifying information
36+
- **Reproducible** — Include sample data or clear instructions for obtaining test data
37+
- **Tested** — Verify that your code runs without errors
38+
39+
## Contribution Ideas by Stack
40+
41+
| Stack | Good Contributions |
42+
|-------|-------------------|
43+
| **InsightStack** | MEL calculators, Stata/SPSS scripts, research templates |
44+
| **FieldStack** | R notebooks, survey tools, evaluation frameworks |
45+
| **EquityStack** | Python scripts, Jupyter notebooks, data workflows |
46+
| **SignalStack** | Research tool recommendations, method spotlights |
47+
| **RootStack** | Database schemas, seed data, SQL queries |
48+
| **BridgeStack** | FastAPI endpoints, data models, API tests |
49+
| **ViewStack** | Frontend components, chart templates, dashboard designs |
50+
| **PolicyStack** | Policy data, budget analysis scripts, government data scrapers |
51+
52+
## Code Style
53+
54+
- **Python:** Follow PEP 8. Use descriptive variable names.
55+
- **R:** Follow the tidyverse style guide. Use snake_case.
56+
- **Stata:** Use clear variable labels and value labels.
57+
- **Markdown:** Use ATX-style headers (`#`). Keep lines under 120 characters.
58+
59+
## Data Standards
60+
61+
- Use **CSV** for tabular data (UTF-8 encoding)
62+
- Include a **data dictionary** or codebook for any new datasets
63+
- **Never commit** real participant data, credentials, or API keys
64+
- Use **sample_data/** directories for test datasets
65+
66+
## Questions?
67+
68+
Open an issue in the relevant repository or email varna.sr@gmail.com.
69+
70+
## Code of Conduct
71+
72+
All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).

‎LICENSE‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
11
MIT License
22

3-
Copyright (c) 2025
3+
Copyright (c) 2025 Varna Sri Raman
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 40 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,72 @@
1-
2-
<p align="center">
3-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
4-
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-updating-blue.svg" alt="Changelog"></a>
5-
<a href="https://buymeacoffee.com/varnasra"><img src="https://img.shields.io/badge/Support-BuyMeACoffee-yellow.svg" alt="Support Me"></a>
6-
</p>
7-
8-
91
# RootStack
102

11-
> Foundational data schemas, seed datasets, and queries powering the OpenStacks ecosystem.
3+
**Foundational data schemas for the OpenStacks ecosystem.**
124

13-
---
5+
[![Part of OpenStacks](https://img.shields.io/badge/Part%20of-OpenStacks-blue)](https://openstacks.dev)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
7+
[![Status: Early Stage](https://img.shields.io/badge/Status-Early%20Stage-orange)]()
148

15-
![RootStack Banner Placeholder](https://via.placeholder.com/1200x300.png?text=RootStack+-+OpenStacks+Foundation)
9+
> The database layer for OpenStacks — schemas, seed data, and queries.
1610
1711
---
1812

19-
# 📚 Table of Contents
20-
- [About](#about)
21-
- [Architecture](#architecture)
22-
- [Folder Structure](#folder-structure)
23-
- [Installation & Usage](#installation--usage)
24-
- [Roadmap](#roadmap)
25-
- [Contributing](#contributing)
26-
- [License](#license)
27-
- [Support Me](#support-me)
28-
- [Citation](#citation)
29-
- [Contact](#contact)
30-
- [Changelog](#changelog)
13+
## Status
3114

32-
---
15+
**This repository is in early development.** The architecture and goals are documented below, but the actual SQL schemas, seed data, and queries have not yet been implemented. Contributions are welcome to help build this out.
3316

34-
# 📖 About
17+
## Vision
3518

36-
**RootStack** is the foundational database layer for the OpenStacks family of tools.
37-
It provides structured database schemas, seed datasets, and example queries for modular, scalable, and open development.
19+
RootStack will provide the foundational data layer for the OpenStacks ecosystem:
3820

39-
RootStack serves as the backbone for BridgeStack (API services) and ViewStack (frontend visualization).
21+
- **Structured schemas** (PostgreSQL/SQLite) for development sector data
22+
- **Seed datasets** for testing and demonstration
23+
- **Example queries** for common analysis patterns
24+
- **Migration scripts** for schema evolution
4025

41-
---
26+
### Planned Architecture
4227

43-
# 🏛️ Architecture
44-
45-
```plaintext
46-
[ RootStack (Database Layer) ]
47-
⇅
48-
[ BridgeStack (API Layer) ]
49-
⇅
50-
[ ViewStack (Frontend Layer) ]
28+
```
29+
RootStack (Database) → BridgeStack (API) → ViewStack (Frontend)
5130
```
5231

53-
RootStack provides clean, well-structured data that flows upward into APIs and user interfaces.
32+
RootStack feeds data to [BridgeStack](https://github.com/Varnasr/BridgeStack) via SQL, which exposes it through a REST API to [ViewStack](https://github.com/Varnasr/ViewStack).
5433

55-
---
34+
### Planned Structure
5635

57-
# 📁 Folder Structure
58-
59-
```plaintext
36+
```
6037
RootStack/
6138
├── schemas/
62-
│ └── tables.sql
39+
│ ├── tables.sql # Core table definitions
40+
│ └── migrations/ # Schema version changes
6341
├── seed_data/
64-
│ └── seed_initial.sql
42+
│ └── seed_initial.sql # Test/demo data
6543
├── queries/
66-
│ └── example_queries.sql
67-
├── README.md
44+
│ └── example_queries.sql # Common query patterns
45+
└── docs/
46+
└── data_dictionary.md # Field descriptions and relationships
6847
```
6948

70-
---
71-
72-
# ⚙️ Installation & Usage
73-
74-
1. Clone the repository:
75-
```bash
76-
git clone https://github.com/Varnasr/RootStack.git
77-
cd RootStack
78-
```
49+
## How to Contribute
7950

80-
2. Set up the database (PostgreSQL recommended):
81-
```bash
82-
psql -U your_user -d your_database -f schemas/tables.sql
83-
psql -U your_user -d your_database -f seed_data/seed_initial.sql
84-
```
85-
86-
3. Explore and adapt queries from `/queries/`.
87-
88-
---
51+
This is a great repo to contribute to if you have experience with:
52+
- PostgreSQL or SQLite schema design
53+
- Development sector data structures (surveys, indicators, program data)
54+
- Database migration workflows
8955

90-
# 🛣️ Roadmap
56+
See the [OpenStacks hub](https://github.com/Varnasr/OpenStacks-for-Change) for ecosystem-wide contribution guidelines.
9157

92-
- [ ] Add multiple schema versions (PostgreSQL + SQLite)
93-
- [ ] Expand sample seed datasets
94-
- [ ] Add database migration templates
95-
- [ ] Integrate versioning system
96-
- [ ] Optimize queries for scalability
58+
## How It Connects
9759

98-
---
99-
100-
# 🤝 Contributing
101-
102-
Contributions are welcome! ✨
103-
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
104-
105-
---
60+
| Stack | Role | Link |
61+
|-------|------|------|
62+
| **RootStack** (this repo) | Database schemas & seed data | You are here |
63+
| [BridgeStack](https://github.com/Varnasr/BridgeStack) | API backend (FastAPI) | Consumes RootStack data |
64+
| [ViewStack](https://github.com/Varnasr/ViewStack) | Frontend UI | Displays BridgeStack API data |
10665

107-
# 📜 License
108-
109-
This project is licensed under the [MIT License](LICENSE).
110-
111-
---
112-
113-
# ☕ Support Me
114-
115-
If you find RootStack helpful, [buy me a coffee](https://buymeacoffee.com/varnasra)!
116-
117-
---
118-
119-
# 📝 Citation
120-
121-
```
122-
@misc{rootstack2025,
123-
author = {Varna Sri Raman},
124-
title = {RootStack: Foundational Database Layer of OpenStacks},
125-
year = {2025},
126-
url = {https://github.com/Varnasr/RootStack}
127-
}
128-
```
129-
130-
---
131-
132-
# 📬 Contact
133-
134-
- 📧 Email: varna.sr@gmail.com
135-
- 🌐 Threads: [@varnasriraman](https://www.threads.net/@varnasriraman)
136-
137-
---
138-
139-
# 📈 Changelog
140-
141-
This project uses an [auto-updating CHANGELOG.md](CHANGELOG.md) generated by GitHub Actions.
142-
143-
---
66+
## License
14467

68+
MIT — free to use, modify, and share. See [LICENSE](LICENSE).
14569

14670
---
14771

148-
<p align="center">
149-
Made with ❤️ by <b>Varna Sri Raman</b> • <a href="https://buymeacoffee.com/varnasra">Support my work</a> • <a href="mailto:varna.sr@gmail.com">Contact</a>
150-
</p>
72+
**Created by [Varna Sri Raman](https://github.com/Varnasr)** — Development Economist & Social Researcher

0 commit comments

Comments
 (0)