update contribution guide #61
Conversation
…d enhancing testing section with TDD practices
…tions of local and docker environments, including recommended tools and their purposes.
|
Thanks for the updates @andersy005! |
There was a problem hiding this comment.
Thanks for updating this! I left a small suggestion to improve the link style on the landing page.
Also some high-level reactions:
- Is "data science" still the title we want to use to describe this bucket of work? At least internally, we don't seem to use this term much anymore.
- Can we delete the front-end contents? They were never fleshed out and I'd rather just omit them at this point.
Co-authored-by: Kata Martin <[email protected]>
Done!
good point. now that we removed the front-end contents, i think it's best to also remove this distinction/hierarchy |
…es on skipping hooks
| ## Local environments | ||
|
|
||
| We primarily use two tools for managing local environments, depending on project needs. | ||
|
|
||
| ### Using Pixi | ||
|
|
||
| [Pixi](https://pixi.sh/latest/) is our recommended tool for managing local environments, especially for projects with complex geospatial dependencies. | ||
|
|
||
| #### Advantages of Pixi | ||
|
|
||
| - Faster dependency resolution than conda/mamba | ||
| - Simplified environment specification and isolation | ||
| - Compatibility with conda-forge packages (crucial for `GDAL`, `rasterio`, etc.) | ||
| - Deterministic builds with lockfiles | ||
|
|
||
| #### Getting Started with Pixi | ||
|
|
||
| Follow the [installation instructions](https://pixi.sh/latest/#installation) to set up Pixi: | ||
|
|
||
| ```bash | ||
| # Install Pixi | ||
| curl -fsSL https://pixi.sh/install.sh | bash | ||
|
|
||
| # Initialize a new project | ||
| pixi init | ||
|
|
||
| # Add dependencies (including conda-forge packages) | ||
| pixi add numpy pandas xarray | ||
| pixi add -c conda-forge gdal rasterio | ||
|
|
||
| # Run commands within the environment | ||
| pixi run python my_script.py | ||
| ``` | ||
|
|
||
| ### Alternative: Conda/Mamba | ||
|
|
||
| For projects that benefit from the broader conda ecosystem, you can use conda or its faster alternative, mamba. |
There was a problem hiding this comment.
@norlandrhagen, i'm curious to hear your thoughts on this section
There was a problem hiding this comment.
@andersy005 I think this is a great update! I've spent a bit of time playing with both uv and pixi this last week. In a really brief exploratory period, I think uv is easier to get setup and use, but still has the conda-forge source limitation. What do you think of having some sort of choice flow diagram like:
graph TD;
A[I have a conda-forge specific dep like xESMF, GDAL etc.]-->|yes| B;
A[I have a conda-forge specific dep like xESMF, GDAL etc.]-->|no| E[Use UV];
B[I want to stick in the conda/mamba ecosystem]-->|yes| C[Use mamba/conda-store];
B-->|no| D[Use Pixi];
There was a problem hiding this comment.
Left one small content suggestion, otherwise this is looking good to me.
Before linking these MDX pages from the landing page, I think we need to address a hydration error (also on main) that affects the styling of all the MDX pages on initial load (see screenshot below). Doesn't need to be a blocker for getting further feedback on the content, but something to track down (@Shane98c or I can also help with this!).
while planning a one-pager on Code Contribution norms, i learned that we've always had a skeleton contribution guide for both data science and front-end projects as part of our docs site/repo. however, the content isn't easy to find on docs.carbonplan.org unless you already know how to navigate the site. instead of duplicating efforts by creating yet another document, i decided to revamp the existing documentation. i'd definitely love feedback from folks on both the content and structure.
The latest deployment resides here: https://docs-git-update-contributor-guide-carbonplan.vercel.app/tech
cc @katamartin / @tracyanderson / @norlandrhagen / @orianac