You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: consolidate contributing guidance into contributing.qmd
Move environment files, pre-commit hooks, and data file policy from
README.md into contributing.qmd as the single source of truth.
Slim README to quick-start setup with a pointer to the Contributing Guide.
Copy file name to clipboardExpand all lines: README.md
+2-35Lines changed: 2 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,41 +26,8 @@ quarto preview # live-preview the site at localhost
26
26
```
27
27
28
28
See the [Contributing Guide](https://nasa.github.io/ASDC_Data_and_User_Services/contributing.html)
29
-
for notebook style and content guidelines.
30
-
31
-
### Environment files
32
-
33
-
This repo has two environment definitions. They serve different purposes:
34
-
35
-
| File | Managed by | Purpose |
36
-
|------|------------|---------|
37
-
|`pyproject.toml` / `uv.lock`|`uv`|**Local development.** All packages needed to run every notebook. Use `uv sync` to install. |
38
-
|`environment.yml`| conda (CI only) |**Site builds.** Minimal Jupyter kernel so Quarto can render pre-executed notebooks. You should not need this locally. |
39
-
40
-
Quarto is configured with `freeze: true`, which means it never re-executes
41
-
notebook code during a build. It converts the already-rendered `.ipynb` outputs
42
-
straight to HTML. This keeps CI fast and avoids the need for data access
43
-
credentials in the build environment.
44
-
45
-
### Pre-commit hooks
46
-
47
-
The pre-commit configuration runs on every commit:
*This contributing guide is a draft, and still under active, open development.*
8
+
*This contributing guide is under active development.*
9
9
10
-
###Style Guidelines
10
+
## Style guidelines
11
11
12
12
The following are recommended and/or enforced via the CI/CD workflow:
13
13
14
-
-**Python Version**: This project requires Python 3.10 or higher. All code and notebooks should be compatible with Python 3.10+.
14
+
-**Python version** — Python 3.10 or higher. All code and notebooks should be compatible with Python 3.10+.
15
15
- Use `ruff` for linting and formatting.
16
16
- Wherever possible and appropriate, move inline comments into notebook Markdown cells.
17
17
- Wherever possible and appropriate, replace static references to local files with code that will programmatically pull data files when running a notebook.
18
18
19
-
###Content Guidelines
19
+
## Content guidelines
20
20
21
21
Ensure each notebook contains, at a minimum:
22
22
23
-
- A quarto header with an auto-generated "last published" date included
23
+
- A Quarto header with an auto-generated "last published" date included
24
24
- A Markdown header section with:
25
25
- A **Summary** or **Overview** block
26
26
- A **Prerequisites** block
27
27
- A **Notebook Author/Affiliation** block
28
-
- Numbered sections that use Markdown hash symbols (#) for headings
28
+
- Numbered sections that use Markdown hash symbols (`#`) for headings
29
+
30
+
## Data files
31
+
32
+
Notebooks should fetch data programmatically at runtime (e.g., via
33
+
`earthaccess` or `harmony-py`) rather than committing data files to the
34
+
repository. Large files such as `.nc`, `.hdf`, and `.h5` are not tracked
35
+
by git and should stay that way.
36
+
37
+
## Environment files
38
+
39
+
This repo has two environment definitions. They serve different purposes:
40
+
41
+
| File | Managed by | Purpose |
42
+
|------|------------|----------|
43
+
|`pyproject.toml` / `uv.lock`|`uv`|**Local development.** All packages needed to run every notebook. Use `uv sync` to install. |
44
+
|`environment.yml`| conda (CI only) |**Site builds.** Minimal Jupyter kernel so Quarto can render pre-executed notebooks. You should not need this locally. |
45
+
46
+
Quarto is configured with `freeze: true`, which means it never re-executes
47
+
notebook code during a build. It converts the already-rendered `.ipynb` outputs
48
+
straight to HTML. This keeps CI fast and avoids the need for data access
49
+
credentials in the build environment.
50
+
51
+
## Pre-commit hooks
52
+
53
+
The pre-commit configuration runs on every commit:
0 commit comments