Expand setup and repository management chapters

Author: jdebacker

README.md

@@ -1,7 +1,7 @@
 [![PSL incubating](https://img.shields.io/badge/PSL-incubating-ff69b4.svg)](https://www.PSLmodels.org)
 
 # <img src="https://raw.githubusercontent.com/PSLmodels/Git-Tutorial/master/book/_static/logo/jb_git_tutorial_logo.png" width=40 /> Git and GitHub Use, Collaboration, and Workflow
-This repository houses the source code and content files for the open access, *Git and GitHub Use, Collaboration, and Workflow* book tutorial and training used by many contributors in the [PSLmodels](https://github.com/PSLmodels) community. This project uses [Jupyter Book](https://jupyterbook.org/intro.html) to create the published HTML version of the tutorial. The source lives in this GitHub repository, and the compiled book is available at [https://pslmodels.github.io/Git-Tutorial](https://pslmodels.github.io/Git-Tutorial). This project is maintained by [Richard W. Evans](https://sites.google.com/site/rickecon/) and [Jason DeBacker](https://www.jasondebacker.com/).
+This repository houses the source code and content files for the open access, *Git and GitHub Use, Collaboration, and Workflow* book tutorial and training used by many contributors in the [PSLmodels](https://github.com/PSLmodels) community. This project uses [Jupyter Book](https://jupyterbook.org/intro.html) and MyST to create the published HTML version of the tutorial. The source lives in this GitHub repository, and the compiled book is available at [https://pslmodels.github.io/Git-Tutorial](https://pslmodels.github.io/Git-Tutorial). This project is maintained by [Richard W. Evans](https://sites.google.com/site/rickecon/) and [Jason DeBacker](https://www.jasondebacker.com/).
 
 
 ## Contributing to the book
@@ -23,24 +23,25 @@ conda activate jb-git-tutorial
 
 ### Building a Jupyter Book
 
-Run the following command in your terminal:
+Run the following command in your terminal from the `book` directory:
 
 ```bash
-jb build ./book
+cd book
+jupyter book build --all
 ```
 
 If you would like to work with a clean build, you can empty the build folder by running:
 
 ```bash
-jb clean ./book
+jupyter book clean
 ```
 
 If jupyter execution is cached, this command will not delete the cached folder.
 
 To remove the build folder (including `cached` executables), you can run:
 
 ```bash
-jb clean --all ./book
+jupyter book clean --all
 ```
 
 ## Notes

book/content/repomgt/documentation.md

@@ -1,6 +1,97 @@
 (chap_docum)=
 # Documentation
 
-Code documentation standards, README.md, Jupyter Book, actual books/manual, Sphinx
+Good documentation lowers the cost of using, reviewing, and contributing to a repository. In many projects, documentation quality is one of the main factors that determines whether a newcomer becomes a contributor or gives up early.
 
-The [Jupyter Book](https://jupyterbook.org/intro.html) documentation has a section in the [MyST Markdown Overview](https://jupyterbook.org/content/myst.html) chapter suggesting that if you are using VS Code to modify markdown files, you should download the [vscode MyST markdown extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) that provides highlighting and other features.
+## Why documentation matters
+
+Documentation helps different audiences answer different questions.
+
+* Users want to know what the project does and how to run it.
+* Contributors want to know how to set up the environment, run tests, and submit changes.
+* Maintainers want project knowledge to live in the repository rather than only in their heads.
+
+Documentation is part of the product, not an afterthought.
+
+## The role of the README
+
+For many repositories, `README.md` is the first page a newcomer sees. A good README usually includes:
+
+* what the repository is for
+* how to install or set it up
+* how to run the project
+* how to contribute
+* where to find more detailed documentation
+
+If the README grows too large, that is often a sign the project is ready for fuller documentation rather than a sign the README should be abandoned.
+
+## Layered documentation
+
+Healthy projects often use several layers of documentation.
+
+* README for quick orientation
+* contributor guide for workflow and setup
+* API or developer docs for code-level detail
+* tutorials or examples for common tasks
+* changelog or release notes for project history
+
+Each layer serves a different purpose.
+
+## Documentation for code and research repositories
+
+In research-oriented open-source work, documentation may need to cover more than software usage. It may also need to explain:
+
+* modeling assumptions
+* data inputs
+* expected outputs
+* limitations and known caveats
+* how results should be interpreted
+
+This kind of context is often essential for reproducibility.
+
+## Documentation tooling
+
+Projects use many different documentation tools. Common options include:
+
+* plain Markdown in the repository
+* Jupyter Book
+* Sphinx
+* notebooks and example galleries
+
+The best tool is often the one the team will maintain consistently.
+
+This repository uses Jupyter Book and MyST Markdown. If you are editing MyST files in VS Code, the [MyST extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) can make the authoring experience smoother.
+
+## What good contributor documentation should cover
+
+A newcomer should not need tribal knowledge to contribute. At minimum, contributor documentation should explain:
+
+* how to create the project environment
+* how to run tests
+* how to build docs, if applicable
+* how to format or lint code
+* the expected pull request workflow
+
+## Treat documentation as part of review
+
+One good maintainer habit is to ask during review: does this change require documentation updates?
+
+Examples include:
+
+* a new feature
+* a changed command-line interface
+* a new dependency
+* a workflow change
+* a changed result or interpretation in a research project
+
+If the answer is yes, the docs should usually change in the same pull request.
+
+## Good habits
+
+* Keep examples current.
+* Prefer concrete commands over vague prose.
+* Write for a reader who does not already know the project.
+* Document the supported setup path explicitly.
+* Fix stale docs quickly once discovered.
+
+Documentation quality compounds over time. A small improvement today often saves many future contributors from the same confusion.

book/content/repomgt/license.md

@@ -1,4 +1,80 @@
 (chap_license)=
 # Open Source License Options
 
-Discuss open source license options as well as private repository options. Benefits and drawbacks of each.
+Choosing a license is one of the most important early decisions for an open-source repository. A license tells other people what they are allowed to do with the code and what obligations come with that use.
+
+## Why a license matters
+
+Without a license, a public GitHub repository may be visible, but others usually do not have clear legal permission to reuse, modify, or redistribute the code.
+
+A clear license:
+
+* makes reuse expectations explicit
+* reduces uncertainty for contributors and users
+* helps organizations decide whether they can adopt the project
+* clarifies how improvements can flow back into the community
+
+## Common open-source license families
+
+Open-source licenses often fall into two broad categories.
+
+### Permissive licenses
+
+Permissive licenses such as MIT, BSD, and Apache 2.0 usually allow broad reuse with relatively few obligations beyond preserving notices and, in some cases, including the license text.
+
+These licenses are often chosen when the project wants to maximize downstream adoption.
+
+### Copyleft licenses
+
+Copyleft licenses such as GPL require derivative works to remain under compatible open-source terms when distributed. These licenses are often chosen when maintainers want changes to remain open in downstream redistributions.
+
+## Questions maintainers should ask
+
+Before choosing a license, it helps to ask:
+
+* Do we want the broadest possible reuse?
+* Do we want derivative works to remain open?
+* Are there funder, employer, or institutional requirements?
+* Are we combining code with dependencies that have license compatibility constraints?
+
+## A practical beginner rule
+
+If you are contributing to an existing repository, do not choose a new license on your own. Follow the license already used by the project and ask maintainers before making changes to licensing files.
+
+If you are starting a new repository, choose a standard well-known license rather than inventing custom terms.
+
+## Private repositories
+
+Not every repository is open source. Some projects are private because they contain sensitive data, internal tools, unpublished research, or code that an organization is not ready to release.
+
+A private repository can still benefit from all the workflow practices described in this book:
+
+* branches
+* pull requests
+* code review
+* CI
+* issue tracking
+
+The difference is access control, not the basic collaboration model.
+
+## Documentation matters too
+
+Once a project chooses a license, that decision should be easy to find.
+
+Good practice includes:
+
+* a top-level `LICENSE` file
+* a short note in the `README.md`
+* consistent statements in package metadata when relevant
+
+## The social side of licensing
+
+Licensing is partly legal, but it is also cultural. A project's license signals something about how it wants to participate in the open-source ecosystem.
+
+For collaborative research repositories, it is often worth pairing the code license with clear guidance on:
+
+* attribution expectations
+* contribution workflow
+* data or documentation licensing, if different from the code
+
+That combination makes the repository easier to understand and safer to contribute to.

book/content/repomgt/testing_CI.md

@@ -1,4 +1,107 @@
 (chap_testCI)=
 # Continuous Integration (CI) and Unit Testing
 
-Give a tutorial on how to set up CI and coverage in a repository. Test driven development (TDD), references. Differences among unit testing, regression testing, and CI.
+As repositories grow, contributors need more than good intentions to keep the default branch working. They need automatic checks that run consistently for every proposed change. This is the role of {term}`continuous integration`, usually abbreviated as CI.
+
+## What CI does
+
+Continuous integration is the practice of running automated checks whenever code is pushed or a pull request is opened or updated. In GitHub-based projects, these checks are often run with GitHub Actions, but the basic idea is broader than any one platform.
+
+Typical CI jobs include:
+
+* running unit tests
+* running style or lint checks
+* building documentation
+* checking that notebooks or examples execute successfully
+* measuring code coverage
+
+The purpose of CI is not to replace human review. It is to catch routine problems quickly and consistently so reviewers can focus on design, correctness, and maintainability.
+
+## Unit testing, regression testing, and CI
+
+These ideas are related, but they are not identical.
+
+### Unit testing
+
+Unit tests check small, individual pieces of the code base. A unit test might verify that one function returns the expected output for a known input.
+
+### Regression testing
+
+Regression tests check that behavior that used to work still works after a change. A regression test may be a unit test, but it can also be a larger end-to-end or integration-style test that guards against reintroducing a known bug.
+
+### Continuous integration
+
+CI is the automation framework that runs tests and other checks whenever the repository changes. CI is the delivery mechanism, not the test itself.
+
+## Why this matters in collaborative repositories
+
+In a shared repository, a broken default branch creates friction for everyone. CI lowers that risk by making sure that each pull request is evaluated under the same rules.
+
+For PSLmodels-style collaboration, CI is especially valuable because repositories often combine code, documentation, examples, and research outputs. A pull request may look harmless in one file while breaking something important elsewhere.
+
+## What a healthy CI setup looks like
+
+A good CI setup is usually:
+
+* fast enough that contributors will actually pay attention to it
+* reliable enough that failures usually mean something real
+* broad enough to test the most important project behavior
+* visible in pull requests so contributors and reviewers can act on results
+
+For a small project, that might mean only a few checks. For a mature project, it might involve several operating systems, multiple Python versions, documentation builds, and separate slow-running jobs.
+
+## A simple CI path for a Python project
+
+Many Python repositories start with something like the following:
+
+1. install project dependencies
+2. run the test suite
+3. run formatting or linting checks
+4. optionally collect coverage
+
+If the project publishes documentation, another good early step is to add a documentation build check so broken examples or malformed Markdown are caught before merge.
+
+## Code coverage
+
+Coverage tools measure how much of your code is exercised by the test suite. Coverage is useful, but it should be interpreted carefully.
+
+Coverage can answer:
+
+* Did our tests execute this function at all?
+* Which files have very little test attention?
+
+Coverage cannot answer:
+
+* Are the tests meaningful?
+* Do the tests assert the right behavior?
+* Are the most important edge cases covered?
+
+High coverage is not the same thing as high quality. Still, coverage reports can be useful for spotting neglected parts of a code base.
+
+## Test-driven development
+
+Test-driven development, or TDD, is the practice of writing a failing test before implementing the code that makes it pass. Some teams use TDD heavily, while others use it selectively.
+
+Even if a project does not follow TDD strictly, it is still a strong habit to add or update tests whenever behavior changes.
+
+## Good contributor habits around CI
+
+* Run relevant tests locally before pushing, when practical.
+* Read the CI failure output rather than guessing.
+* Keep fixes for a failing check on the same pull request branch.
+* Treat flaky tests as real maintenance problems.
+* Make sure documentation changes are tested if the repo has docs automation.
+
+## Good maintainer habits around CI
+
+* Keep required checks clear and documented.
+* Avoid adding slow or brittle checks without strong benefit.
+* Make failure messages readable.
+* Update CI when the supported environment changes.
+* Keep secrets and deployment credentials out of general-purpose workflows.
+
+## Start simple
+
+Beginners sometimes think a project needs an elaborate CI system before it can benefit from automation. In practice, even a single workflow that installs dependencies and runs tests can dramatically improve collaboration quality.
+
+The best CI setup is usually one that the team understands, trusts, and maintains.