Skip to content

Commit 5707bd0

Browse files
Copilotinfomofo
Copilot
and
infomofo
authored
Add comprehensive GitHub Copilot instructions and fix CI workflow for scala-ssml (#22)
* Initial plan * Initial exploration and validation of scala-ssml repository Co-authored-by: infomofo <539599+infomofo@users.noreply.github.com> * Add comprehensive GitHub Copilot instructions and update .gitignore Co-authored-by: infomofo <539599+infomofo@users.noreply.github.com> * Fix GitHub Actions workflow to install SBT before running tests Co-authored-by: infomofo <539599+infomofo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: infomofo <539599+infomofo@users.noreply.github.com>
1 parent 9a4af5c commit 5707bd0

File tree

3 files changed

+139
-1
lines changed

3 files changed

+139
-1
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Scala SSML Library
2+
This is a Scala library for generating Speech Synthesis Markup Language (SSML) with fluent method chaining. It's designed for use with Alexa Skills, Google Assistant, and browser Text-To-Speech engines.
3+
4+
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.
5+
6+
## Working Effectively
7+
8+
### Install SBT (Required)
9+
SBT is not pre-installed and must be set up manually:
10+
```bash
11+
# Download and extract SBT 1.3.8 (matches project/build.properties)
12+
curl -L -o sbt-1.3.8.tgz "https://github.com/sbt/sbt/releases/download/v1.3.8/sbt-1.3.8.tgz"
13+
tar -xzf sbt-1.3.8.tgz
14+
# Use ./sbt/bin/sbt for all subsequent commands
15+
```
16+
17+
### Build, Test, and Package
18+
```bash
19+
# Compile the project
20+
./sbt/bin/sbt compile # Takes ~20 seconds (first time includes bridge compilation)
21+
22+
# Run all tests - NEVER CANCEL: Set timeout to 30+ minutes for safety
23+
./sbt/bin/sbt test # Takes ~8 seconds. All 3 tests should pass.
24+
25+
# Create JAR package
26+
./sbt/bin/sbt package # Takes ~5 seconds. Creates target/scala-2.13/scala-ssml_2.13-0.4.0.jar
27+
28+
# Generate API documentation
29+
./sbt/bin/sbt doc # Takes ~7 seconds. Creates target/scala-2.13/api/index.html
30+
```
31+
32+
### Interactive Development
33+
```bash
34+
# Start Scala console with project on classpath
35+
./sbt/bin/sbt console # Takes ~10 seconds to start
36+
37+
# Example usage in console:
38+
# scala> import com.infomofo.scalassml.SSMLBuilder
39+
# scala> val ssml = SSMLBuilder().text("hello").pause(1000).text("goodbye")
40+
# scala> println(ssml.trimmedXml)
41+
# scala> :quit
42+
```
43+
44+
### Cross-Compilation Limitations
45+
Do NOT attempt cross-compilation with `+compile` or `+test`. The project is configured for Scala 2.11.12 and 2.12.11 cross-compilation, but scala-xml 2.2.0 dependency is not available for Scala 2.11, causing build failures.
46+
47+
## Validation
48+
49+
### Always Test Core Functionality
50+
After making changes to the SSML generation code, always validate with these scenarios in the Scala console:
51+
52+
```scala
53+
import com.infomofo.scalassml.SSMLBuilder
54+
55+
// Basic text with pause
56+
val basic = SSMLBuilder().text("hello").pause(1000).text("goodbye")
57+
println(basic.trimmedXml)
58+
// Expected: <speak>hello<break time="1000s"/>goodbye</speak>
59+
60+
// Complex SSML with multiple features
61+
val complex = SSMLBuilder()
62+
.sentence("Hello world")
63+
.comma()
64+
.ipaPhoneme("namaste", "ˈnʌməsteɪ")
65+
.pause(2)
66+
.characters("ABC")
67+
println(complex.trimmedXml)
68+
// Expected: <speak><s>Hello world</s><break strength="weak"/><phoneme alphabet="ipa" ph="ˈnʌməsteɪ">namaste</phoneme><break time="2s"/><say-as interpret-as="characters">ABC</say-as></speak>
69+
70+
// Verify card text extraction
71+
println(complex.getCardText)
72+
// Expected: Hello world namaste ABC (plain text, no XML)
73+
```
74+
75+
### Verify CI Compatibility
76+
The GitHub Actions workflow (`.github/workflows/test.yml`) runs `sbt test` with JDK 1.8. While local development works with Java 17, ensure your changes don't break with older Java versions by checking test output carefully.
77+
78+
## Common Tasks
79+
80+
### Repository Structure
81+
```
82+
├── README.md # Usage documentation and examples
83+
├── build.sbt # Main build configuration (Scala 2.13.13)
84+
├── project/
85+
│ ├── build.properties # SBT version (1.3.8)
86+
│ └── Dependencies.scala # ScalaTest dependency
87+
├── src/
88+
│ ├── main/scala/com/infomofo/scalassml/
89+
│ │ └── SSMLBuilder.scala # Core SSML generation library
90+
│ └── test/scala/com/infomofo/scalassml/
91+
│ └── SSMLBuilderSpec.scala # Test suite (3 tests)
92+
└── .github/workflows/test.yml # CI configuration
93+
```
94+
95+
### Key APIs to Know
96+
- `SSMLBuilder()` - Start building SSML
97+
- `.text(string)` - Add plain text
98+
- `.sentence(string)` - Wrap text in `<s>` tags
99+
- `.pause(seconds)` - Add `<break time="Ns"/>`
100+
- `.comma()` - Add weak break `<break strength="weak"/>`
101+
- `.ipaPhoneme(text, pronunciation)` - Add IPA phoneme markup
102+
- `.characters(text)` - Spell out characters using `<say-as interpret-as="characters">`
103+
- `.alias(text, substitute)` - Text substitution with `<sub>`
104+
- `.trimmedXml` - Get clean XML Node representation
105+
- `.getCardText` - Extract plain text (no XML markup)
106+
107+
### No Formatting/Linting Tools
108+
This project has no built-in code formatting, style checking, or linting tools configured. Maintain consistency with existing code style manually.
109+
110+
### Dependencies
111+
- **scala-xml 2.2.0**: XML manipulation and generation
112+
- **scalatest 3.1.2**: Testing framework (Test scope only)
113+
- **Scala 2.13.13**: Primary Scala version
114+
- **Java 17**: Runtime (despite .java-version specifying 1.11)
115+
116+
### Troubleshooting
117+
- **"sbt: command not found"**: Download and extract SBT manually as shown above
118+
- **Cross-compilation fails**: Expected behavior due to scala-xml 2.2.0 unavailability for Scala 2.11
119+
- **Network warnings during SBT**: Normal in sandboxed environments, builds complete successfully
120+
- **Java SecurityManager warnings**: Expected with newer Java versions, safe to ignore
121+
122+
### Example Build Session
123+
```bash
124+
# Complete build and validation workflow
125+
curl -L -o sbt-1.3.8.tgz "https://github.com/sbt/sbt/releases/download/v1.3.8/sbt-1.3.8.tgz"
126+
tar -xzf sbt-1.3.8.tgz
127+
./sbt/bin/sbt compile test package doc
128+
# Total time: ~40 seconds for complete build cycle
129+
```

‎.github/workflows/test.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,9 @@ jobs:
1313
uses: actions/setup-java@v1
1414
with:
1515
java-version: 1.8
16+
- name: Install SBT
17+
run: |
18+
curl -L -o sbt-1.3.8.tgz "https://github.com/sbt/sbt/releases/download/v1.3.8/sbt-1.3.8.tgz"
19+
tar -xzf sbt-1.3.8.tgz
1620
- name: Run tests
17-
run: sbt test
21+
run: ./sbt/bin/sbt test

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,8 @@ target/
22
lib_managed/
33
.idea/
44
*/.DS_Store
5+
6+
# Temporary build tools (should be downloaded locally as needed)
7+
sbt/
8+
sbt-*.tgz
9+
cs

0 commit comments

Comments
 (0)