Skip to content

Commit 6184df7

Browse files
nixel2007nixel2007
authored
Merge pull request #582 from 1c-syntax/copilot/setup-copilot-instructions
Add GitHub Copilot repository instructions
2 parents c614c80 + 8fe6729 commit 6184df7

1 file changed

Lines changed: 197 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# MDClasses Repository Instructions
2+
3+
## Overview
4+
5+
MDClasses is a Java library for reading and analyzing metadata from 1C:Enterprise 8 platform. The library works with configurations exported in XML format (via configurator or merge/comparison tools) or in EDT format.
6+
7+
**Project Type**: Java library
8+
**Build Tool**: Gradle with Kotlin DSL
9+
**Primary Language**: Java 17+
10+
**Target Runtime**: JVM (Java 17, 21, 25 tested)
11+
**Repository Size**: Medium-sized Java project with extensive test coverage
12+
13+
## Build and Test Instructions
14+
15+
### Prerequisites
16+
- Java 17 or higher (tested on Java 17, 21, and 25)
17+
- Git with LFS support for test data
18+
- No additional environment setup required
19+
20+
### Bootstrap and Build Commands
21+
22+
**Always initialize Git submodules and LFS when cloning:**
23+
```bash
24+
git submodule update --init --recursive
25+
git lfs pull
26+
```
27+
28+
**Build the project:**
29+
```bash
30+
./gradlew build
31+
```
32+
33+
**Run tests only:**
34+
```bash
35+
./gradlew test
36+
```
37+
38+
**Run quality checks (includes tests and code quality):**
39+
```bash
40+
./gradlew check
41+
```
42+
43+
**Generate Javadoc:**
44+
```bash
45+
./gradlew javadoc
46+
```
47+
48+
**Run all precommit checks:**
49+
```bash
50+
./gradlew precommit
51+
```
52+
This runs tests and updates license headers.
53+
54+
**Update license headers:**
55+
```bash
56+
./gradlew updateLicenses
57+
```
58+
59+
**Clean build artifacts:**
60+
```bash
61+
./gradlew clean
62+
```
63+
64+
### Build Notes
65+
- The build uses Gradle wrapper (`./gradlew` on Unix, `gradlew.bat` on Windows)
66+
- Always use the wrapper to ensure consistent Gradle version
67+
- Test results are located in `build/reports/tests/test/`
68+
- JaCoCo coverage reports are in `build/reports/jacoco/test/`
69+
- Build time: typically 1-2 minutes for full build with tests
70+
71+
### Common Build Issues
72+
- If tests fail due to missing test data, ensure Git LFS is properly initialized
73+
- Lombok annotations are used extensively - IDE should have Lombok plugin installed
74+
- If seeing "out of memory" errors, set `org.gradle.jvmargs=-Xmx2048m` in `gradle.properties`
75+
76+
## Project Structure
77+
78+
### Key Directories
79+
- `src/main/java/` - Main source code
80+
- `com/github/_1c_syntax/bsl/reader/` - Core readers for different formats
81+
- `com/github/_1c_syntax/bsl/mdo/` - Metadata object model classes
82+
- `com/github/_1c_syntax/bsl/mdclasses/` - Main library API
83+
- `src/test/java/` - Test code
84+
- `src/test/resources/` - Test fixtures and sample configurations
85+
- `src/main/resources/` - XSD schemas and converters
86+
- `docs/` - Documentation (MkDocs format, Russian and English)
87+
- `.github/workflows/` - CI/CD pipelines
88+
89+
### Key Configuration Files
90+
- `build.gradle.kts` - Main build configuration (Gradle Kotlin DSL)
91+
- `settings.gradle.kts` - Gradle settings
92+
- `gradle.properties` - Build properties
93+
- `lombok.config` - Lombok configuration
94+
- `mkdocs.yml` / `mkdocs.en.yml` - Documentation configuration
95+
- `.github/workflows/java-ci.yml` - Main CI pipeline
96+
- `.github/workflows/gh-pages.yml` - Documentation deployment
97+
- `license/HEADER.txt` - License header template
98+
99+
### Main Entry Points
100+
- `com.github._1c_syntax.bsl.mdclasses.MDClasses` - Main API class for loading configurations
101+
- `com.github._1c_syntax.bsl.mdo.Configuration` - Root configuration object
102+
- `com.github._1c_syntax.bsl.reader.designer.DesignerReader` - XML format reader
103+
- `com.github._1c_syntax.bsl.reader.edt.EDTReader` - EDT format reader
104+
105+
## CI/CD Validation
106+
107+
### GitHub Actions Workflows
108+
1. **Java CI** (`.github/workflows/java-ci.yml`)
109+
- Runs on: push and pull request
110+
- Tests matrix: Java 17, 21, 25 on Ubuntu, Windows, macOS
111+
- Command: `./gradlew check --stacktrace`
112+
- Duration: ~5-10 minutes
113+
- Artifacts: Test results uploaded for all matrix combinations
114+
115+
2. **GitHub Pages** (`.github/workflows/gh-pages.yml`)
116+
- Runs on: push to master/develop when docs change
117+
- Builds Javadoc and MkDocs documentation
118+
- Requires Python 3.10+ and Java 17
119+
120+
### Pre-commit Validation Steps
121+
Before submitting a PR, ensure:
122+
1. All tests pass: `./gradlew test`
123+
2. Code quality checks pass: `./gradlew check`
124+
3. License headers are up to date: `./gradlew updateLicenses`
125+
4. If touching docs, verify locally: `pip install mkdocs mkdocs-material pygments-bsl && mkdocs serve`
126+
127+
## Code Conventions
128+
129+
### Java Code Style
130+
- Target Java 17, use modern Java features where appropriate
131+
- Use Lombok annotations for reducing boilerplate (`@Getter`, `@Setter`, `@Builder`, etc.)
132+
- Package naming: `com.github._1c_syntax.bsl.*`
133+
- Follow standard Java naming conventions
134+
- UTF-8 encoding for all files
135+
- License headers required on all Java files (automatically updated via Gradle task)
136+
137+
### Project-Specific Patterns
138+
- This is a **read-only** library - it does not modify configurations
139+
- Metadata objects follow 1C:Enterprise naming and structure
140+
- XStream is used for XML serialization/deserialization
141+
- Use `@Nullable` and `@NonNull` annotations from `org.jspecify`
142+
- Converters pattern used for transforming between different representations
143+
- Extensive use of ClassGraph for runtime class discovery
144+
145+
### Testing Guidelines
146+
- JUnit 5 is used for testing
147+
- AssertJ for fluent assertions
148+
- Test resources include real 1C configuration samples
149+
- Tests are organized by functionality/reader type
150+
- Mock objects avoided in favor of integration tests with real data
151+
152+
## Dependencies
153+
154+
### Key Runtime Dependencies
155+
- `bsl-common-library` - Common 1C:Enterprise language utilities
156+
- `utils` - General utilities
157+
- `supportconf` - Support configuration handling
158+
- XStream - XML processing
159+
- Apache Commons Collections 4 - Collection utilities
160+
- Commons IO - File operations
161+
- ClassGraph - Runtime class discovery
162+
- SLF4J - Logging facade
163+
164+
### Test Dependencies
165+
- JUnit 5 - Testing framework
166+
- AssertJ - Fluent assertions
167+
- JSONAssert - JSON comparison in tests
168+
- Reload4j - Logging implementation for tests
169+
170+
## Additional Notes
171+
172+
### Working with 1C:Enterprise
173+
- The library handles two main formats:
174+
1. **Designer (XML)** format - exported via 1C:Enterprise configurator
175+
2. **EDT** format - modern development environment format
176+
- Metadata structure mirrors 1C:Enterprise concepts (Catalogs, Documents, Registers, etc.)
177+
- Russian language is primary for domain concepts (alternate English names often available)
178+
179+
### Documentation
180+
- Dual-language documentation (Russian primary, English available)
181+
- Javadoc is comprehensive and should be maintained
182+
- MkDocs for user-facing documentation
183+
- Update docs when changing public API
184+
185+
### Performance
186+
- Benchmark tools available (`src/jmh/`)
187+
- JMH benchmarks for performance testing
188+
- Results stored in `build/jmh-results.json`
189+
190+
### Integration
191+
- Library is designed to be used by BSL Language Server
192+
- Maven Central releases for public consumption
193+
- Snapshot builds deployed to Sonatype for testing
194+
195+
## Trust These Instructions
196+
197+
These instructions have been validated against the current codebase. Trust them as accurate and only search for additional information if something is incomplete or contradicts observed behavior.

0 commit comments

Comments
 (0)