basant307/AI_Governance_Project

1# How to Contribute2 3We would love to accept your patches and contributions to this project.4 5## Contribution Process6 7### Code Reviews8 9All submissions, including submissions by project members, require review. We10use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)11for this purpose.12 13### Pull Request Guidelines14 15To help us review and merge your PRs quickly, please follow these guidelines. PRs that do not meet these standards may be closed.16 17#### 1. Link to an Existing Issue18 19All PRs should be linked to an existing issue in our tracker. This ensures that every change has been discussed and is aligned with the project's goals before any code is written.20 21- **For bug fixes:** The PR should be linked to the bug report issue.22- **For features:** The PR should be linked to the feature request or proposal issue that has been approved by a maintainer.23 24If an issue for your change doesn't exist, please **open one first** and wait for feedback before you start coding.25 26#### 2. Keep It Small and Focused27 28We favor small, atomic PRs that address a single issue or add a single, self-contained feature.29 30- **Do:** Create a PR that fixes one specific bug or adds one specific feature.31- **Don't:** Bundle multiple unrelated changes (e.g., a bug fix, a new feature, and a refactor) into a single PR.32 33As a rule of thumb, start splitting a PR once it exceeds about 1,200 changed34lines. PRs above about 2,000 changed lines should either be split into a series35of smaller, logical PRs that can be reviewed and merged independently, or36explain in the PR description why the change needs to land together.37 38#### 3. Use Draft PRs for Work in Progress39 40If you'd like to get early feedback on your work, please use GitHub's **Draft Pull Request** feature. This signals to the maintainers that the PR is not yet ready for a formal review but is open for discussion and initial feedback.41 42#### 4. Ensure All Checks Pass43 44Before submitting your PR, ensure that all automated checks are passing by running `npm run preflight`. This command runs all tests, linting, and other style checks.45 46#### 5. Update Documentation47 48If your PR introduces a user-facing change (e.g., a new command, a modified flag, or a change in behavior), you must also update the relevant documentation in the `/docs` directory.49 50#### 6. Include a Screenshot or Video Demo51 52To help reviewers understand your change quickly and prioritize reviews, please attach a screenshot or short video to your PR showing the change in action.53 54- **For bug fixes:** Show the before and after behavior.55- **For new features:** Show the feature working end-to-end.56- **For refactors or internal-only changes:** Simply note "N/A — no user-facing change" in the demo section.57 58PRs with visual demos tend to get reviewed much faster, so this is in your interest too!59 60#### 7. Write Clear Commit Messages and a Good PR Description61 62Your PR should have a clear, descriptive title and a detailed description of the changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for your commit messages.63 64- **Good PR Title:** `feat(cli): Add --json flag to 'config get' command`65- **Bad PR Title:** `Made some changes`66 67In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., `Fixes #123`).68 69### Adding a Provider Preset70 71A built-in preset is an **endorsement**, not just a convenience. Users route API keys and full prompt data through these endpoints, so the bar is high.72 73**Tier 1 — Built-in Preset** requires all of the following:74 75- **Affiliation Disclosure** — PR author must disclose any relationship with the provider.76- **Operational Maturity** — publicly operational with demonstrated uptime; public SLA or status page preferred.77- **Organic User Demand** — evidence of community demand (issues, discussions), not just a self-listing.78- **Data and Security Transparency** — provider's data handling practices must be publicly documented.79- **Maintenance Commitment** — provider team commits to tracking Qwen Code protocol changes.80 81**Default Path — Custom Provider**: for providers that don't meet Tier 1, users connect via the built-in custom-provider flow (`/auth` or `/model` → Custom Provider). No code change or project endorsement needed.82 83**If a Tier 1 preset is approved**, the PR should follow the existing `openrouter.ts` / `requesty.ts` pattern: use `customHeaders` for attribution, implement `ownsModel` with a dual-gate (env key + hostname), and add the env key to `SECRET_ENV_VARS` in `packages/cli/src/serve/envSnapshot.ts` with corresponding test assertions in `auth.test.ts` and `provider-config.test.ts`.84 85## Development Setup and Workflow86 87This section guides contributors on how to build, modify, and understand the development setup of this project.88 89### Setting Up the Development Environment90 91**Prerequisites:**92 931.  **Node.js**:94    - **Development:** Please use Node.js `>=22`. Ink 7 (used by the TUI) requires Node 22, and `react@^19.2.0` is the matching peer. You can use a tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.95    - **Production:** For running the CLI in a production environment, any version of Node.js `>=22` is acceptable.962.  **Git**97 98### Build Process99 100To clone the repository:101 102```bash103git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL104cd qwen-code105```106 107To install dependencies defined in `package.json` as well as root dependencies:108 109```bash110npm install111```112 113To build the entire project (all packages):114 115```bash116npm run build117```118 119This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to `scripts/build.js` and `package.json` scripts for more details on what happens during the build.120 121### Enabling Sandboxing122 123[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `QWEN_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details.124 125To build both the `qwen-code` CLI utility and the sandbox container, run `build:all` from the root directory:126 127```bash128npm run build:all129```130 131To skip building the sandbox container, you can use `npm run build` instead.132 133### Running134 135To start the Qwen Code application from the source code (after building), run the following command from the root directory:136 137```bash138npm start139```140 141If you'd like to run the source build outside of the qwen-code folder, you can utilize `npm link path/to/qwen-code/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) to run with `qwen-code`142 143### Running Tests144 145This project contains two types of tests: unit tests and integration tests.146 147#### Unit Tests148 149To execute the unit test suite for the project:150 151```bash152npm run test153```154 155This will run tests located in the `packages/core` and `packages/cli` directories. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run `npm run preflight`.156 157#### Integration Tests158 159The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default `npm run test` command.160 161To run the integration tests, use the following command:162 163```bash164npm run test:e2e165```166 167For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./docs/developers/development/integration-tests.md).168 169### Linting and Preflight Checks170 171To ensure code quality and formatting consistency, run the preflight check:172 173```bash174npm run preflight175```176 177This command will run ESLint, Prettier, all tests, and other checks as defined in the project's `package.json`.178 179_ProTip_180 181after cloning create a git precommit hook file to ensure your commits are always clean.182 183```bash184echo "185# Run npm build and check for errors186if ! npm run preflight; then187  echo "npm build failed. Commit aborted."188  exit 1189fi190" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit191```192 193#### Formatting194 195To separately format the code in this project by running the following command from the root directory:196 197```bash198npm run format199```200 201This command uses Prettier to format the code according to the project's style guidelines.202 203#### Linting204 205To separately lint the code in this project, run the following command from the root directory:206 207```bash208npm run lint209```210 211### Coding Conventions212 213- Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.214- **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages.215 216### Project Structure217 218- `packages/`: Contains the individual sub-packages of the project.219  - `cli/`: The command-line interface.220  - `core/`: The core backend logic for Qwen Code.221- `docs/`: Contains all project documentation.222- `scripts/`: Utility scripts for building, testing, and development tasks.223 224For more detailed architecture, see `docs/architecture.md`.225 226## Documentation Development227 228This section describes how to develop and preview the documentation locally.229 230### Prerequisites231 2321. Ensure you have Node.js (version 22+) installed2332. Have npm or yarn available234 235### Setup Documentation Site Locally236 237To work on the documentation and preview changes locally:238 2391. Navigate to the `docs-site` directory:240 241   ```bash242   cd docs-site243   ```244 2452. Install dependencies:246 247   ```bash248   npm install249   ```250 2513. Link the documentation content from the main `docs` directory:252 253   ```bash254   npm run link255   ```256 257   This creates a symbolic link from `../docs` to `content` in the docs-site project, allowing the documentation content to be served by the Next.js site.258 2594. Start the development server:260 261   ```bash262   npm run dev263   ```264 2655. Open [http://localhost:3000](http://localhost:3000) in your browser to see the documentation site with live updates as you make changes.266 267Any changes made to the documentation files in the main `docs` directory will be reflected immediately in the documentation site.268 269## Debugging270 271### VS Code:272 2730.  Run the CLI to interactively debug in VS Code with `F5`2741.  Start the CLI in debug mode from the root directory:275    ```bash276    npm run debug277    ```278    This command runs `node --inspect-brk dist/index.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger.2792.  In VS Code, use the "Attach" launch configuration (found in `.vscode/launch.json`).280 281Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended.282 283To hit a breakpoint inside the sandbox container run:284 285```bash286DEBUG=1 qwen-code287```288 289**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect qwen-code due to automatic exclusion. Use `.qwen-code/.env` files for qwen-code specific debug settings.290 291### React DevTools292 293To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x.294 2951.  **Start the Qwen Code application in development mode:**296 297    ```bash298    DEV=true npm start299    ```300 3012.  **Install and run React DevTools version 4.28.5 (or the latest compatible 4.x version):**302 303    You can either install it globally:304 305    ```bash306    npm install -g react-devtools@4.28.5307    react-devtools308    ```309 310    Or run it directly using npx:311 312    ```bash313    npx react-devtools@4.28.5314    ```315 316    Your running CLI application should then connect to React DevTools.317 318## Sandboxing319 320> TBD321 322## Manual Publish323 324We publish an artifact for each commit to our internal registry. But if you need to manually cut a local build, then run the following commands:325 326```327npm run clean328npm install329npm run auth330npm run prerelease:dev331npm publish --workspaces332```333