Skip to content

CDA GUI Contributing Docs #1246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
krowvin wants to merge 1 commit into
base: develop
Choose a base branch
from
Draft

CDA GUI Contributing Docs #1246

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 23 additions & 27 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@

Thanks for thinking about using or contributing to this software ("Project") and its documentation!

* [Policy & Legal Info](#policy)
* [Getting Started](#getting-started)
* [Submitting an Issue](#submitting-an-issue)
* [Submitting Code](#submitting-code)
- [Policy & Legal Info](#policy)
- [Getting Started](#getting-started)
- [Submitting an Issue](#submitting-an-issue)
- [Submitting Code](#submitting-code)
- [CDA GUI Docs](/cda-gui.README.md)

## Policy

Expand Down Expand Up @@ -83,7 +84,6 @@ this repository and any help on the formatting code and such will be greatly app

Now you're ready to [clone the repository](https://help.github.com/articles/cloning-a-repository/) and start looking at things. If you are going to submit any changes you make, please read the Submitting changes section below.


### Code Style

If you are editing an existing file please be consistent with the style in the file.
Expand All @@ -92,13 +92,13 @@ Otherwise use the defined checkstyle format for new code.

#### SQL Coding

1. Use the JOOQ wrapper. Generally the wrapper provides sufficiently reasonable query generation.
However, *DO NOT* be afraid to say, "that looks terrible", and tweak it until it generates something better.
a. If the query you're making has nested queries name the queries. Example
```sql
1. Use the JOOQ wrapper. Generally the wrapper provides sufficiently reasonable query generation.
However, _DO NOT_ be afraid to say, "that looks terrible", and tweak it until it generates something better.
a. If the query you're making has nested queries name the queries. Example
Copy link
Contributor

@MikeNeilson MikeNeilson Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
a. If the query you're making has nested queries name the queries. Example
a. If the query you're making has nested queries, name the queries. Example

`sql
select a.* from (select col1,col2 from a_table) a;
```
Otherwise JOOQ creates a new name each time the query is run which can starved the shared memory.
`
Otherwise JOOQ creates a new name each time the query is run which can starved the shared memory.
Copy link
Contributor

@MikeNeilson MikeNeilson Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Otherwise JOOQ creates a new name each time the query is run which can starved the shared memory.
Otherwise JOOQ creates a new name each time the query is run which can starve the shared memory.


2. Joins are your friend. They are a much better friend IF you let the database do them for you. Do not pull data into java just to do a join. Write the appropriate SQL.
3. Whenever possible limit by office first.
Expand All @@ -115,15 +115,13 @@ However, *DO NOT* be afraid to say, "that looks terrible", and tweak it until it
1. Assume the following when creating and naming your test:
a. Someone will come in cold to the entire project.
b. The tests will be used by API users to guide their client application designs
3. For repeated tests with different, but very similar data, ParameterizedTests are preferred.
4. In integration tests for data that should be cleaned up after all tests register them with the functions available in the base class. Create if reasonable.
5. If it adds clarity, do not be afraid to use the `@Order` annotation to sequence tests. (See the [ApiKey Controller Test](https://github.com/USACE/cwms-data-api/blob/develop/cwms-data-api/src/test/java/cwms/cda/api/auth/ApiKeyControllerTestIT.java) for an example)
6. Prefer disabling test by database schema version, if that does work use `EnabledIfProperty` and share a property name between related tests.
7. Use "real" names for data in test data set. Either use actual real location/project/basin/etc names, or make up something that feels like one.
a. NOTE: within reason. Location names, absolutely, but otherwise make sure the purpose of the name is clear.
8. Name files consistent with the purpose of the test.


2. For repeated tests with different, but very similar data, ParameterizedTests are preferred.
3. In integration tests for data that should be cleaned up after all tests register them with the functions available in the base class. Create if reasonable.
4. If it adds clarity, do not be afraid to use the `@Order` annotation to sequence tests. (See the [ApiKey Controller Test](https://github.com/USACE/cwms-data-api/blob/develop/cwms-data-api/src/test/java/cwms/cda/api/auth/ApiKeyControllerTestIT.java) for an example)
5. Prefer disabling test by database schema version, if that does work use `EnabledIfProperty` and share a property name between related tests.
6. Use "real" names for data in test data set. Either use actual real location/project/basin/etc names, or make up something that feels like one.
a. NOTE: within reason. Location names, absolutely, but otherwise make sure the purpose of the name is clear.
7. Name files consistent with the purpose of the test.

## Submitting an Issue

Expand All @@ -133,23 +131,21 @@ You should feel free to [submit an issue](https://github.com/<needs name>) on ou

When submitting a bug report, please be sure to include accurate and thorough information about the problem you're observing. Be sure to include:

* Steps to reproduce the problem,
* What you expected to happen,
* What actually happened (or did not happen),
* Technical details including the specific version number of CWMS Data API (CDA) you are using,
* Sanitized logs - NO IP Addresses, usernames, etc.
- Steps to reproduce the problem,
- What you expected to happen,
- What actually happened (or did not happen),
- Technical details including the specific version number of CWMS Data API (CDA) you are using,
- Sanitized logs - NO IP Addresses, usernames, etc.

## Submitting Code

Please [fork](https://help.github.com/en/articles/fork-a-repo) the repository on github and create a [branch in Git](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) if you are making changes to existing code.


Once you have made your changes submit a [pull request](https://help.github.com/en/articles/creating-a-pull-request-from-a-fork).
Please submit all PRs to the develop branch.

Barring nothing working at all or the code not being related to CWMS Data API your contributions will be accepted.


## Releases an branching

If you have write access to the repository you can create release. All release should be put in a release/X.Y branch.
Expand Down
98 changes: 98 additions & 0 deletions cda-gui.README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# CDA - Graphical User Interface

## Index

- [Quick Start](#quick-start)
- [New Page](#adding-a-new-page)
- [Components](#using-pre-defined-components)

## Running the Development Server

### Standalone

You can run the CDA GUI on your local system without tomcat.

#### Perquisites

- Install [`NodeJS`](https://nodejs.org/en/download)

#### Quick Start

1. `cd gda-gui`
2. `npm install` (NodeJS Required)
3. `npm run dev`
4. Open https://localhost:5173/cwms-data

Changes will now be hot reloaded in the browser as you update your React files.

### Deployed Locally in the WAR

- 🚧 WIP

## Helpful Tips

### Adding a New Page

1. Add a new directory to `cda-gui/src/my-page/`
2. Create an `index.jsx` in the new directory
3. Create a component function along the lines of:

```jsx
export default function MyPage() {
return <div>Example Page</div>;
}
```

You can view current page examples [here - /cda-guid/src/pages](/cda-gui/src/pages/)

4. Add the new path/component to the client-side routing:

1. Open [main.jsx](/cda-gui/src/main.jsx) in [/cda-gui/src](/cda-gui/src)
2. Import your new component (top of file) with:
```jsx
import MyPage from "./pages/my-page";
```
3. Add a new Object to the `children` of `createBrowserRouter`

```javascript
// Make sure to import MyPage at the top!
{ path: "my-page", element: <MyPage /> },
```

5. Update [cda-gui/src/links/header-links.js](/cda-gui/src/links/header-links.js) to include your new route.
The common structure of a given url is:
```javascript
{
id: "tools",
text: "Tools",
href: "tools",
children: {
id: "my-page",
text: "My Page",
href: "/my-page"
}
}
```
The `children` key is optional, only if you want an additional dropdown from the menu.
_(Groundwork supports nesting 2 deep!)_

### Using Pre-Defined Components

CWMS Data API GUI makes use of the [Groundwork](https://usace.github.io/#/), a React library to add stylized USACE themed components.

For Water Management components it uses [Groundwork-Water](https://usace-watermanagement.github.io/groundwork-water/#/), a React component library that uses [CWMSjs](https://hydrologicengineeringcenter.github.io/cwms-data-api-client-javascript/) to wrap CDA calls.

### Environment Files

CDA has 4 primary environments. Each of these environments targets what the GUI will use when deployed.

The environments each have their own file:

| Environment | File Name | Host |
| ----------- | --------------------------------------------- | ------ |
| Local | .env.local | System |
| Development | [.env.development](/cda-gui/.env.development) | Cloud |
| Test | [.env.test](/cda-gui/.env.test) | Cloud |
| Production | [.env.production](/cda-gui/.env.production) | Cloud |

Where the `.env.local` file is not typically committed!
Loading