Skip to content

Commit 585af49

Browse files
lazarusAlazarusA
authored
contribute
contributions update
2 parents 512be0c + 44dc23a commit 585af49

File tree

3 files changed

+215
-135
lines changed

3 files changed

+215
-135
lines changed

‎CONTRIBUTING.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Contributors Guide
2+
3+
Thank you for your interest in contributing to `netcdf4-wasm`! We welcome everyone, whether you're new to open source, WebAssembly, TypeScript, or scientific computing, or an experienced developer. Every contribution, big or small, helps make this project better.
4+
5+
If you have questions, ideas, or just want to chat, please reach out to us anytime. We're happy to help and discuss anything related to `netcdf4-wasm`, NetCDF, or science in general.
6+
7+
## How You Can Contribute
8+
9+
* **Report bugs or suggest features:** [Open a GitHub issue](https://github.com/EarthyScience/netcdf4-wasm/issues/new/) to let us know about problems or ideas.
10+
* **Start or join a discussion:** [Create a GitHub discussion](https://github.com/EarthyScience/netcdf4-wasm/discussions/new/choose) to ask questions, share experiences, or brainstorm.
11+
* **Improve documentation:** Help us make our docs clearer and more helpful for everyone.
12+
* **Write code:** Fix bugs, add features, or improve performance.
13+
* **Add examples:** Create usage examples or tutorials showing how to use `netcdf4-wasm` in different scenarios.
14+
15+
### Tips for Creating Issues
16+
17+
The most helpful bug reports:
18+
19+
* Include a clear code snippet (not just a link) that shows the problem in the latest version of `netcdf4-wasm`. A ["minimal working example"](https://en.wikipedia.org/wiki/Minimal_working_example) is ideal.
20+
* Paste the full error message you received, even if it's long.
21+
* Use triple backticks (```` ``` ````) for code, and [markdown formatting](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) to keep things readable.
22+
* Share your `netcdf4-wasm` version, Node.js/browser version, and details about your environment (OS, browser, etc.).
23+
24+
Discussions are great for questions about usage, implementation, WebAssembly compilation, NetCDF formats, or anything else.
25+
26+
## Development Setup
27+
28+
To start developing `netcdf4-wasm`:
29+
30+
1. [Fork the `netcdf4-wasm` repository](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks) and clone your fork
31+
2. Navigate to the project directory
32+
3. Install dependencies:
33+
```bash
34+
npm install
35+
```
36+
4. Check that you have all build dependencies:
37+
```bash
38+
npm run check-deps
39+
```
40+
5. If you need Emscripten for building WASM:
41+
```bash
42+
npm run install-emscripten
43+
```
44+
6. Build the project:
45+
```bash
46+
npm run build
47+
```
48+
7. Run tests to ensure everything works:
49+
```bash
50+
npm test
51+
```
52+
53+
### Project Structure
54+
55+
Understanding the project structure will help you navigate the codebase:
56+
```
57+
netcdf4-wasm/
58+
├── src/ # TypeScript source code
59+
│ ├── __tests__/ # Test files
60+
│ ├── constants.ts # NetCDF constants
61+
│ ├── dimension.ts # Dimension class
62+
│ ├── group.ts # Group class
63+
│ ├── index.ts # Main API exports
64+
│ ├── netcdf-getters.ts # Data getter utilities
65+
│ ├── netcdf-worker.ts # Web Worker implementation
66+
│ ├── netcdf4-wasm.d.ts # TypeScript declarations
67+
│ ├── netcdf4.ts # Main NetCDF4 class
68+
│ ├── test-setup.ts # Test configuration
69+
│ ├── types.ts # Type definitions
70+
│ ├── variable.ts # Variable class
71+
│ └── wasm-module.ts # WASM module loader
72+
├── scripts/ # Build scripts
73+
│ ├── build-wasm.sh # Main WASM build script
74+
│ ├── check-dependencies.sh
75+
│ └── install-emscripten.sh
76+
├── bindings/ # WASM bindings
77+
│ ├── pre.js # Pre-run JavaScript
78+
│ └── post.js # Post-run JavaScript
79+
├── build/ # Build artifacts (generated)
80+
├── dist/ # Distribution files (generated)
81+
└── package.json
82+
```
83+
84+
## Making Your Contribution
85+
86+
1. [Fork the repository](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks), make your changes, and [open a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). We'll review and help you get it merged.
87+
2. For small fixes (like typos), you can use the [GitHub editor](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository) for a quick edit and pull request.
88+
3. Please try to follow our code style and formatting conventions.
89+
4. Always test your changes before submitting:
90+
```bash
91+
# Run all tests
92+
npm test
93+
94+
# Run tests with coverage
95+
npm run test:coverage
96+
97+
# Run tests in watch mode while developing
98+
npm run test:watch
99+
```
100+
101+
## Good First Steps
102+
103+
* Try out `netcdf4-wasm` using the examples in our documentation. If you hit any problems or have questions, please open an issue!
104+
* Write an example or tutorial showing how to use `netcdf4-wasm` for reading/writing NetCDF files in the browser or Node.js.
105+
* Suggest improvements to documentation or code comments.
106+
* Work on issues labeled `good first issue` or `help wanted`.
107+
* Improve TypeScript type definitions for better developer experience.
108+
* Add or improve test coverage.
109+
110+
If you want to work on something, let us know by commenting on an issue or opening a new one. This helps us coordinate and support you.
111+
112+
## Useful Commands
113+
114+
Here are the main commands you'll use during development:
115+
```bash
116+
# Install dependencies
117+
npm install
118+
119+
# Build the entire project (WASM + TypeScript)
120+
npm run build
121+
122+
# Build only the WASM module
123+
npm run build:wasm
124+
125+
# Build only TypeScript
126+
npm run build:ts
127+
128+
# Clean build artifacts
129+
npm run clean
130+
131+
# Run tests
132+
npm test
133+
134+
# Run tests with coverage
135+
npm run test:coverage
136+
137+
# Run tests in watch mode
138+
npm run test:watch
139+
```
140+
141+
## Code of Conduct
142+
143+
We are committed to providing a welcoming and inclusive environment. Please be respectful, kind, and constructive in all interactions. We do not tolerate harassment or discriminatory behavior of any kind.
144+
145+
## Getting Help
146+
147+
* **Questions about usage?** Open a [GitHub discussion](https://github.com/EarthyScience/netcdf4-wasm/discussions)
148+
* **Found a bug?** Open an [issue](https://github.com/EarthyScience/netcdf4-wasm/issues)
149+
* **Want to chat?** Reach out to the maintainers
150+
151+
We're excited to have you join our community. Thank you for helping make `netcdf4-wasm` better!

‎LICENSE‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
MIT License
22

33
Copyright (c) 2024 netcdf4-wasm
4+
Copyright (c) 2025 Lazaro Alonso, Jeran Poehls
45

56
Permission is hereby granted, free of charge, to any person obtaining a copy
67
of this software and associated documentation files (the "Software"), to deal

0 commit comments

Comments
 (0)