Skip to content

Commit 0b4da03

Browse files
nonprofittechynonprofittechy
authored
Merge pull request #976 from SuffolkLITLab/copilot/fix-975
Create comprehensive GitHub Copilot instructions for docassemble-AssemblyLine development workflow
2 parents aa2f5ce + b5cd58b commit 0b4da03

File tree

1 file changed

+110
-0
lines changed

1 file changed

+110
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Suffolk LIT Lab Document Assembly Line Package
2+
3+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
4+
5+
## Working Effectively
6+
7+
### Bootstrap, build, and test the repository:
8+
- `python3 -m pip install --upgrade pip`
9+
- `python3 -m pip install -e .` -- installs package in development mode. Takes 30-60 seconds. NEVER CANCEL. May fail with network timeouts; retry if needed.
10+
- `python3 setup.py sdist` -- builds package distribution. Takes <1 second.
11+
- `python3 -c "import docassemble.AssemblyLine; print('Version:', docassemble.AssemblyLine.__version__)"` -- verifies package imports correctly
12+
13+
### Linting and type checking:
14+
- Install linting tools: `python3 -m pip install black mypy types-PyYAML pandas-stubs types-psycopg2 pillow pikepdf sqlalchemy[mypy]`
15+
- `black --check docassemble/AssemblyLine` -- checks code formatting. Takes <5 seconds.
16+
- `black docassemble/AssemblyLine` -- auto-formats code if needed. Takes <5 seconds.
17+
- `mypy docassemble/AssemblyLine --config-file pyproject.toml` -- type checking. Takes 3-5 seconds. NEVER CANCEL.
18+
19+
### Testing:
20+
- **Unit Tests**: Python unit tests exist in `test_*.py` files but require full docassemble environment to run. DO NOT attempt to run them locally - they will fail with import errors.
21+
- **Integration Tests**: Use ALKiln framework with `.feature` files in `docassemble/AssemblyLine/data/sources/`. These require a running docassemble server and browser automation.
22+
- **GitHub Actions Testing**:
23+
- `ALKiln v5 tests` workflow runs integration tests on every push - takes 15-30 minutes. NEVER CANCEL.
24+
- `Run python only unit tests` workflow uses `SuffolkLITLab/ALActions/pythontests@main` - takes 5-10 minutes. NEVER CANCEL.
25+
- `formatting action` workflow runs black and docsig formatting checks - takes 2-3 minutes.
26+
27+
## Validation
28+
29+
- **NEVER try to run Python unit tests locally** - they require the full docassemble framework which cannot be installed in most development environments.
30+
- Always run `black --check` and `mypy` before committing changes.
31+
- Always verify package imports with the import test command above.
32+
- The build process is very fast (<1 second) so always run `python3 setup.py sdist` to verify no syntax errors.
33+
- Test your changes by creating simple interview files in `docassemble/AssemblyLine/data/questions/` and verifying they don't break the package structure.
34+
- **Manual validation**: After making code changes, always run: `python3 -c "import docassemble.AssemblyLine; print('Package imports successfully')"` to ensure the package structure is valid.
35+
36+
## Common tasks
37+
38+
### Repository structure:
39+
```
40+
/
41+
├── .github/workflows/ # GitHub Actions CI/CD
42+
├── docassemble/AssemblyLine/ # Main Python package
43+
│ ├── data/questions/ # 35 YAML interview files
44+
│ ├── data/sources/ # Test files (.feature) and translations
45+
│ ├── data/static/ # CSS, JS, images
46+
│ ├── data/templates/ # Document templates (.docx, .pdf)
47+
│ ├── *.py # 13 Python modules (core functionality)
48+
│ └── test_*.py # Unit tests (require docassemble server)
49+
├── setup.py # Package configuration
50+
├── pyproject.toml # Tool configuration (black, mypy)
51+
├── README.md # Installation and usage docs
52+
└── bumpversion.sh # Version bump script
53+
```
54+
55+
### Core Python modules:
56+
- `al_general.py` - Core classes (ALAddress, ALIndividual, etc.)
57+
- `al_document.py` - Document assembly classes (ALDocument, ALDocumentBundle)
58+
- `al_courts.py` - Court-related functionality
59+
- `sessions.py` - Session management
60+
- `language.py` - Internationalization support
61+
- `sign.py` - Digital signature support
62+
63+
### Key interview files:
64+
- `assembly_line.yml` - Main Assembly Line package include
65+
- `ql_baseline.yml` - Question library baseline
66+
- `test_*.yml` - Test interviews used by ALKiln
67+
68+
### Development workflow:
69+
1. Make code changes to `.py` files
70+
2. Run `black docassemble/AssemblyLine` to format
71+
3. Run `mypy docassemble/AssemblyLine --config-file pyproject.toml` to type check
72+
4. Run `python3 setup.py sdist` to verify build works
73+
5. Test imports: `python3 -c "import docassemble.AssemblyLine; print('OK')"`
74+
6. Commit changes - GitHub Actions will run full test suite
75+
76+
### ALKiln Testing Framework:
77+
- ALKiln is a Node.js tool that automates browser testing of docassemble interviews
78+
- Requires: `npm install -g @suffolklitlab/alkiln` (needs Chrome/Chromium)
79+
- Test files: `*.feature` files in `docassemble/AssemblyLine/data/sources/`
80+
- Uses Gherkin syntax to define test scenarios
81+
- Tests run against live docassemble server instances
82+
- **CRITICAL**: ALKiln tests take 15-30 minutes per run. NEVER CANCEL.
83+
- Local ALKiln testing requires full docassemble server setup which is complex
84+
85+
### Timing expectations:
86+
- Package installation: 30-60 seconds (dependency downloads)
87+
- Build (`setup.py sdist`): <1 second
88+
- Code formatting (black): <5 seconds
89+
- Type checking (mypy): 3-5 seconds
90+
- GitHub Actions ALKiln tests: 15-30 minutes. NEVER CANCEL.
91+
- GitHub Actions Python tests: 5-10 minutes. NEVER CANCEL.
92+
93+
### DO NOT do these things:
94+
- Do not attempt to run unit tests locally (`python3 -m unittest` will fail)
95+
- Do not try to install full docassemble server locally (complex, requires Docker)
96+
- Do not cancel long-running GitHub Actions workflows
97+
- Do not modify the core docassemble dependencies without careful testing
98+
99+
### Always check these files when making changes:
100+
- `docassemble/AssemblyLine/__init__.py` - for version updates
101+
- `setup.py` - for dependency changes
102+
- `pyproject.toml` - for tool configuration
103+
- Related `.yml` interview files when changing Python classes
104+
105+
### Package publication:
106+
- Use `./bumpversion.sh` to increment version numbers
107+
- Builds are automatically published to PyPI via GitHub Actions
108+
- Package is also deployed to Suffolk LIT Lab's development docassemble server
109+
110+
This package is a docassemble library for legal document assembly, providing reusable components for creating guided online court forms. It's part of the Suffolk LIT Lab's broader Assembly Line project for increasing access to justice through technology.

0 commit comments

Comments
 (0)