# Pastebin sL4RIxrg
# OpenStack Development Environment

## Repository Structure
This is a meta-repository containing multiple OpenStack projects:
- **ironic/**: Bare metal provisioning service
- **ironic-python-agent/**: Agent for hardware introspection and provisioning
- **ironic-specs/**: Design specifications for Ironic
- **nova/**: Compute service for managing VM instances
- **nova-specs/**: Design specifications for Nova
- **networking-baremetal/**: Neutron plugin for bare metal networking
- **networking-generic-switch/**: ML2 driver for managing physical switches
- **openstackclient/**: Command-line client for OpenStack APIs
- **openstacksdk/**: Python SDK for OpenStack APIs
- **oslo.*/**: Oslo common libraries (config, log, messaging, etc.)

When needed, you can checkout other OpenStack projects from https://opendev.org/openstack/projectname
as needed for context. If you do, check them out into this directory and add them to the above list.

**Important**: Always use existing checkouts of projects that are already present in this directory. Do not re-clone repositories that are already checked out.

## Development Standards


### Python Code Style
- Follow PEP 8 guidelines
- Use 4-space indentation
- Maximum line length: 79 characters
- Use type hints for new code where they already exist in surrounding code.
- Docstrings required for all public functions/classes
- All imports must be grouped at the top of the file, with stdlib in one group, external libraries in the next group, and internal project imports in another group.

### Testing
- Run tests with tox: `tox -e py312` from the root of a project
- To test a single test module; use `tox -epy312 -- path.to.python.tests.module`. Do not attempt to shrink your testrunning scope to anything smaller than a module.
- Unit tests required for all new features
- Functional tests for API changes
- Use unittest.mock for mocking
- Test files follow pattern: test_*.py
- **CRITICAL RULE**: never ever try to run tests using any method other than execution of tox
- `tox` commands must be run from the root of the relevant project, and not from the root of the metaproject dir.

### Common Commands
- Lint: `tox -e pep8` or `tox -e flake8`
- Type checking: `tox -e mypy` (where configured)
- Documentation: `tox -e docs`
- Release notes: `tox -e releasenotes`

### Release Notes and Documentation
- Releasenote stubs are created by running `reno new topic-for-release-note` from the project root.
- Releasenotes are required for any change which would be noticible by a user of the software, espeically for breaking changes.


## Project-Specific Notes

### Ironic
- Focuses on bare metal provisioning
- Key modules: conductor, api, drivers
- Database migrations in ironic/db/sqlalchemy/alembic
- Configuration in ironic/conf/

### Nova
- VM compute service
- Key modules: compute, scheduler, conductor, api
- Cell-based architecture for scaling
- Placement service integration for resource tracking

### Oslo Libraries
- Shared libraries across OpenStack projects
- Changes here affect multiple projects
- Extra careful with backwards compatibility
- Each has its own tox.ini and testing requirements

## Common Workflows

### Bug Fixes
1. Check if bug exists in latest master
2. Write failing test case first
3. Implement fix
4. Update unit tests
5. Add release note if user-visible change

### Feature Development
1. Check if spec required (nova-specs, ironic-specs)
2. Write/update API documentation
3. Implement with tests
4. Update configuration options if needed
5. Add release note

### Cross-Project Changes
- Changes affecting multiple projects need coordination
- Oslo library changes need compatibility consideration
- API changes need version bumping but should be avoided if possible

## Git Workflow
- Each project is a separate git repository
- Follow OpenStack commit message format
- Include bug/blueprint reference in commit message
- Squash commits before submitting for review
- Identify yourself using a "Generated-By: claude-code" tag at the bottom of the commit. You can also include a small stanza in the actual commit message body about the initial prompt.

## Dependencies
- requirements.txt: Runtime dependencies
- test-requirements.txt: Test dependencies
- doc-requirements.txt: Documentation-building dependencies.
- bindep.txt: System-level dependencies
- Use upper-constraints.txt from OpenStack requirements to constrain.

## DevStack Integration
- Most projects have devstack/ directory
- plugin.sh: DevStack plugin script
- settings: Configuration for DevStack

## Documentation
- Doc source in doc/ directory
- Build with: `tox -e docs`
- API reference in api-ref/ (where applicable)
- Release notes in releasenotes/

## Important Files
- setup.cfg: Package metadata and entry points
- tox.ini: Test environment configuration
- zuul.d/ or .zuul.conf: CI job definitions
- .gitignore: Version control exclusions

## Release Notes
- OpenStack release notes are created by running `reno new short-description-of-change`. This creates a file in the repository, usually releasenotes/notes, starting with short-description-of-change. Then edit this template, removing unneeded headings and detailing the change.

## Code Review and Linting
- No change is complete until lint; usually run via `tox -epep8` passes. Code has to be added to the git staging area before running pep8 jobs in most repositories.

## Terminology Notes
- When referring to the "nova virt driver", this means nova.virt.driver.ironic code which Nova uses as a client to Ironic.

## Tox Environment Usage
- You can use the existing tox environments as a virtualenv to use for executing one-off commands that require the openstack project in question to run. 
- Activate them by looking in the .tox/ directory. 
- A directory starting with py* is more likely to be valid for your uses.