diff --git a/README.md b/README.md new file mode 100644 index 0000000..d718d2a --- /dev/null +++ b/README.md @@ -0,0 +1,109 @@ +# SWT Landing Repository + +This repository is the district-level landing space for SWT work that does not belong cleanly in a single application or service repository. + +Use this repo to track cross-cutting work, coordination items, and district concerns that affect multiple repositories, teams, or deliverables. + +## Purpose + +This repo is intended for: + +- District-level issues that span multiple repositories +- Coordination work that needs a single parent issue +- Tracking items that will later break into repo-specific sub-issues +- General SWT backlog items that do not yet have a better home + +This repo is **not** intended to replace repo-specific issues. If work belongs fully within another repository, open the issue there. + +## When To Open An Issue Here + +Open an issue in this repo when the work: + +- Affects multiple SWT-managed repositories +- Needs one parent issue to coordinate several downstream changes +- Represents a district data/content/process concern rather than a single-app bug +- Is still being defined and should not be anchored to one implementation repo yet + +Examples: + +- Add upstream/downstream gages to Tulsa records in the database, with follow-on updates needed in multiple SWT applications +- Track a district-wide migration or rollout item that requires work across several repos +- Capture a general SWT need first, then split execution into repo-specific issues + +## When Not To Open An Issue Here + +Open the issue in the implementation repo instead when the work is specific to one codebase or one upstream dependency. + +Examples: + +- Waiting on CDA to add a feature for querying an endpoint: track that in the CDA repo +- Waiting on `cwms-database` to add a new table: track that in the `cwms-database` repo +- A bug or feature request that only impacts one SWT application: open it in that application repo + +## Recommended Issue Pattern + +For cross-repo work, use this repo as the parent tracking issue and create linked sub-issues in the affected repositories. + +Example pattern: + +1. Open a parent issue in this repo describing the district-level need. +2. Create sub-issues in each affected repo for the implementation work. +3. Link the sub-issues back to the parent issue. +4. Use the parent issue to track scope, dependencies, and completion status. + +Example: + +- Parent issue in `swt`: Add upstream/downstream gage support for Tulsa records +- Sub-issue in `swt-wm-web-internal`: add `/ds/us` feature in DB view/internal workflows +- Sub-issue in `swt-wm-web`: ensure public hourly content includes upstream/downstream gage support +- Sub-issue in `swt-wm-web-internal`: ensure internal hourly content stays aligned with the public implementation where appropriate + +Some work may stay entirely in this repo if it is general enough and does not require separate implementation issues. + +## Team + +Primary district development team: + +- GitHub team mention: `@USACE-WaterManagement/swt-devs` +- Team page: [USACE-WaterManagement/swt-devs](https://github.com/orgs/USACE-WaterManagement/teams/swt-devs) + +Using the GitHub team mention is the most maintainable option if team membership changes over time. As long as the org team stays current, the README does not need to be updated with individual names. + +If needed later, this section can also be expanded with named points of contact or role-based ownership. + +## SWT Repositories + +Primary repositories currently maintained by or closely associated with SWT: + +- [USACE-WaterManagement/swt](https://github.com/USACE-WaterManagement/swt) +- [usace/swt-wm-web](https://github.com/usace/swt-wm-web) +- [usace-wm/swt-wm-web-internal](https://github.com/usace-wm/swt-wm-web-internal) +- [usace-wm/swt-wm-cwbi-jobs](https://github.com/usace-wm/swt-wm-cwbi-jobs) + +Add to this list as ownership changes. + +## Shared Repositories And District Areas + +Some work may live in shared repositories but still have SWT-owned or SWT-relevant directories. + +Examples: + +- `wm/cavi-scripts` -> `swt` + +This section is intended to document where SWT work exists outside SWT-named repositories. + +## Related Links + +Add district links and coordination resources here: + +- Internal SWT landing page: `TODO add internal landing page URL` +- Org-level migration/change chart project: `TODO add project URL` + +## Working Agreement + +This repo should stay lightweight and useful: + +- Keep parent issues focused on district scope and coordination +- Push implementation details into the relevant repo-specific issues +- Link related issues clearly so status is easy to follow +- Update this README as repo ownership, team structure, or tracking practices evolve