From 30b7788438fafd4bf5d2492aee3dc03195cad0fa Mon Sep 17 00:00:00 2001 From: Maor Rozenfeld <49363375+maor-rozenfeld@users.noreply.github.com> Date: Thu, 20 Nov 2025 14:26:14 +0100 Subject: [PATCH] Add AGENTS.md --- .cursor/rules/coding-guidelines.mdc | 135 ---------------------- .junie/guidelines.md | 64 +---------- AGENTS.md | 169 ++++++++++++++++++++++++++++ 3 files changed, 170 insertions(+), 198 deletions(-) delete mode 100644 .cursor/rules/coding-guidelines.mdc create mode 100644 AGENTS.md diff --git a/.cursor/rules/coding-guidelines.mdc b/.cursor/rules/coding-guidelines.mdc deleted file mode 100644 index a31f8ef690..0000000000 --- a/.cursor/rules/coding-guidelines.mdc +++ /dev/null @@ -1,135 +0,0 @@ ---- -description: Coding guidelines -globs: -alwaysApply: true ---- - ---- - -## General Principles - -- **Follow existing code style and patterns in the repository.** -- **Write clear, self-documenting code** with descriptive variable and function names. -- **Include comments** for complex logic or non-obvious behavior. -- **Write tests** for new functionality and any changes. -- **Update documentation** for user-facing changes. - ---- - -## Formatting & Linting - -- **Indentation:** 2 spaces (TypeScript/JavaScript). -- **Line length:** 100–120 characters preferred. -- **Braces:** Required for all control blocks, even single-line. -- **Spacing:** - - One space between keywords and parentheses: `if (condition) {` - - No trailing whitespace. - - Newline at end of file. -- **Linting:** Use ESLint as configured in each package. - - Example: - ``` - nx lint - ``` -- **Formatting:** Follow Prettier rules if configured. - ---- - -## Naming Conventions - -- **Variables/Functions:** `camelCase` -- **Classes/Types:** `PascalCase` -- **Constants:** `UPPER_SNAKE_CASE` -- **Files:** Use lowercase with hyphens (e.g., `user-profile.ts`) - ---- - -## Language-Specific Notes - -- **TypeScript/JavaScript (Nx Monorepo):** - - Use types and interfaces where appropriate. - - Prefer `const` over `let` or `var`. - - Prefer arrow functions for callbacks and functional components. - - Use explicit return types for exported functions. -- **Tests:** - - Place unit tests alongside the code in a `tests` folder - - Use Jest for testing -- **Shell scripts:** Use `#!/usr/bin/env bash` and indent with 2 spaces. - ---- - -## Comments - -- Explain _why_ something is done, not _what_ (the code should be self-explanatory). -- Use `TODO:` for actionable technical debt. -- Document public functions, classes, and modules. - ---- - -## Dependencies - -- Do not introduce new dependencies without discussion. -- Keep dependency lists minimal and up-to-date. - ---- - -## Tooling - -- Respect `.editorconfig`, `.eslintrc`, `.prettierrc`, and other config files in the repository. - -### Testing & Linting - -Use nx at the root of the project to run unit tests, for example: -nx test react-ui -nx lint react-ui -nx test ui-components -nx test-unit server-api -nx test engine - ---- - -## Example (TypeScript) - -```typescript -// Good Example -export function getUserProfile(userId: string): UserProfile { - if (!userId) { - throw new Error('User ID required'); - } - // TODO: Replace with real data source - return { id: userId, name: 'Sample User' }; -} -``` - -## Frontend Guidelines - -- Use the `react-ui` package for main application logic. -- Place pure, reusable components in the `ui-components` package, documented in Storybook. -- Don't do breaking changes to existing code interfaces (like component props or names, unless this was discussed) -- **Tech stack must strictly use:** - - React 18 - - Zustand - - react-query v5 - - shadcn - - Axios (we already have a wrapper in api.ts), use `qs` package for query strings -- Place and write tests in a separate `tests` folder. -- Ensure compliance with strict linter setups (including Sonar). -- Follow best practices for React hooks. -- Prefer small, composable components. Extract helper functions where possible. -- Use `cn` utility to group tailwind classnames, for example: - -``` -
- {t('Sample output data')} -
-``` diff --git a/.junie/guidelines.md b/.junie/guidelines.md index a4c50f2116..73dd28050d 100644 --- a/.junie/guidelines.md +++ b/.junie/guidelines.md @@ -1,63 +1 @@ -# Guidelines for Junie - -This document provides guidelines for contributing to the OpenOps project, focusing on pull requests and commit practices. - -## Pull Request Guidelines - -### Size and Scope - -- **Prefer small PRs**: Keep pull requests focused on a single feature, bug fix, or improvement. -- **Small commits**: Break down your work into logical, small commits that each represent a complete change. -- **One change per PR**: The PR should only contain changes related to the issue, with no unrelated modifications. - -### Naming and Formatting - -- **Use imperative mood** for PR titles and commit messages (e.g., "Add feature" not "Added feature" or "Adding feature"). -- **PR title requirements** (as defined in `.github/prlint.json`): - - Must start with a capital letter and a real word (e.g., "Add GO support") - - Must have at least three words - - Must use imperative mood (e.g., "Fix bug" not "Fixed bug" or "Fixing bug") - -### Creating Pull Requests - -1. **Use GitHub CLI to create a draft PR**: - ```bash - # Create a draft PR - gh pr create --draft --title "Add feature name" --body "Fixes #12345" - ``` - -2. **Reference issues**: - - Reference a GitHub issue in the PR body (e.g., "Fixes #12345") - - Reference a Linear issue if one was mentioned (e.g., "Fixes OPS-1234") - - If no relevant issue exists, create a GitHub issue first: - ```bash - # Create a GitHub issue - gh issue create --title "Issue title" --body "Issue description" - ``` - -3. **Follow the PR template**: - - Provide a clear description of the changes - - Complete the testing checklist - - Include visual changes if applicable - -## Commit Guidelines - -- **Use imperative mood** in commit messages (e.g., "Fix bug" not "Fixed bug") -- **Keep commits small and focused** on a single change -- **Write descriptive commit messages** that explain what the change does and why -- **Follow this format** for commit messages: - ``` - Short summary in imperative mood (under 50 chars) - - More detailed explanation if necessary. Wrap at around 72 - characters. Explain what and why, not how (the code shows that). - - Fixes #issue_number - ``` - -## Additional Resources - -- [CONTRIBUTING.md](../CONTRIBUTING.md): General contribution guidelines -- [.github/pull_request_template.md](../.github/pull_request_template.md): PR template -- [.github/prlint.json](../.github/prlint.json): PR linting rules -- [docs.openops.com](https://docs.openops.com): Official OpenOps documentation +See AGENTS.md in root folder. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..26cd6745d1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,169 @@ +## General Principles + +- Follow existing code style and patterns in the repository +- Write clear, self-documenting code with descriptive variable and function names +- Include comments for complex logic or non-obvious behavior +- Always write tests for new functionality and changes +- Update documentation for user-facing changes +- Do not introduce new dependencies without discussion + + +## Structure + +The repository is using nx, with the source code under the "packages" directory. +Use nx to run tests (e.g. npx nx test server-shared). +Run "npx nx lint" before committing. + +## Code Style + +### Formatting + +- **Indentation:** 2 spaces (TypeScript/JavaScript, shell scripts) +- **Line length:** 100–120 characters preferred +- **Braces:** Required for all control blocks, even single-line +- **Spacing:** + - One space between keywords and parentheses: `if (condition) {` + - No trailing whitespace + - Newline at end of file +- **Linting:** Use ESLint as configured in each package +- **Formatting:** Follow Prettier rules if configured +- Respect `.editorconfig`, `.eslintrc`, `.prettierrc`, and other config files + +### Naming Conventions + +- **Variables/Functions:** `camelCase` +- **Classes/Types:** `PascalCase` +- **Constants:** `UPPER_SNAKE_CASE` +- **Files:** Lowercase with hyphens (e.g., `user-profile.ts`) + +### Comments + +- Explain _why_ something is done, not _what_ (the code should be self-explanatory) +- Use `TODO:` for actionable technical debt +- Document public functions, classes, and modules + +## TypeScript/JavaScript + +### General Guidelines + +- Use types and interfaces where appropriate +- Prefer `const` over `let` or `var` +- Prefer arrow functions for callbacks and functional components +- Use explicit return types for exported functions + +### Example + +```typescript +export function getUserProfile(userId: string): UserProfile { + if (!userId) { + throw new Error('User ID required'); + } + // TODO: Replace with real data source + return { id: userId, name: 'Sample User' }; +} +``` + +## Frontend Guidelines + +### Project Structure + +- Use the `react-ui` package for main application logic +- Place pure, reusable components in the `ui-components` package, documented in Storybook +- Place and write tests in a separate `tests` folder + +### Tech Stack + +- **React 18** +- **Zustand** for state management +- **react-query v5** for data fetching +- **shadcn** for UI components +- **Axios** (use existing wrapper in `api.ts`), use `qs` package for query strings + +### Best Practices + +- Follow best practices for React hooks +- Prefer small, composable components +- Extract helper functions where possible +- Do not make breaking changes to existing code interfaces (component props, names) without discussion +- Ensure compliance with strict linter setups (including Sonar) +- Use `cn` utility to group Tailwind classnames: + +```tsx +
+ {t('Sample output data')} +
+``` + +## Testing + +- Use Jest for testing +- Place unit tests in a `tests` folder alongside the code +- Run tests using Nx commands: + +```bash +nx test react-ui +nx test ui-components +nx test-unit server-api +nx test engine +nx lint react-ui +``` + +## Git Workflow + +### Commits + +- Use imperative mood (e.g., "Fix bug" not "Fixed bug" or "Fixing bug") +- Keep commits small and focused on a single change +- Write descriptive commit messages that explain what and why, not how + +**Commit message format:** + +``` +Short summary in imperative mood (under 50 chars) + +More detailed explanation if necessary. Wrap at around 72 +characters. Explain what and why, not how (the code shows that). + +Fixes #issue_number +``` + +### Pull Requests + +#### Size and Scope + +- Keep PRs focused on a single feature, bug fix, or improvement +- Break down work into logical, small commits +- Only include changes related to the issue, no unrelated modifications + +#### Title Requirements + +- Must start with a capital letter and a real word +- Must have at least three words +- Must use imperative mood (e.g., "Add GO support" not "Added GO support") + +#### Reference an issue + +All PRs must reference a linear issue in their body. + +Examples: +- Fixes OPS-100. +- Resolves OPS-101. +- Part of CI-102. + +## Additional Resources + +- [CONTRIBUTING.md](./CONTRIBUTING.md) - General contribution guidelines +- [.github/pull_request_template.md](./.github/pull_request_template.md) - PR template +- [.github/prlint.json](./.github/prlint.json) - PR linting rules +- [docs.openops.com](https://docs.openops.com) - Official OpenOps documentation