diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ec6d236 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# The Joy of Coding: Agent Instructions + +This repository supports a Java and Android software-development course. +Prioritize learning, clear communication, and small, student-understandable +changes over completing work quickly. + +## Academic integrity and scope + +- Do not assist with quizzes or exams. They must be completed without Gen AI, + online resources, or other reference materials. +- The multi-phase course project is individual work. Do not retrieve, inspect, + compare, copy, or combine another student's project code. +- Keep student work in a private GitHub repository. Do not retrieve, compare, + or combine another student's code, and do not suggest making the assignment + repository public while the course is in progress. +- Pair and mob programming are limited to the designated in-class katas. Kata + repositories may be public; individual project repositories must remain + private. +- Help a student understand requirements, diagnose a problem, design a small + change, or review code they have written. Do not generate a complete + assignment solution or make broad, solution-sized changes from a starter + repository. +- Before implementing a nontrivial change, explain the approach and let the + student retain ownership of the decision. Encourage the student to be able + to explain each submitted change in their own words. + +## Java and Android + +- Write idiomatic, straightforward Java that matches the concepts already used + by the assignment. Avoid unnecessary frameworks, code generation, + reflection, and advanced patterns. +- The course uses Java for Android work. Acknowledge Kotlin when relevant, but + do not introduce Kotlin unless the assignment explicitly requires it. +- Follow the Google Java Style Guide. Use clear names, conventional package and + class organization, and readable control flow. Do not use wildcard imports. +- Preserve assignment-specified packages, public APIs, command-line switches, + and starter-code structure. +- Do not add third-party dependencies or otherwise change `pom.xml` just to + solve an assignment problem. In particular, do not add third-party libraries + like Spring or Apache Commons. Use JDK APIs and the starter code patterns instead. +- Before submission, remove debugging `println` output and keep only source + files under `src`. If a project has a `-README` switch, it should print only + the required brief formatted description for the student and assignment. +- Treat the Maven Wrapper as the standard build entry point. Prefer + `./mvnw verify` (or `mvnw.cmd` on Windows) and preserve the course's + existing Maven structure. + + +## Design and documentation + +- Begin each project with a concise, plain-text plan of attack: two to four + paragraphs describing the design and implementation approach, not code. +- Add Javadoc for every application class and method written for the project. + Describe behavior, and use `@param`, `@return`, and `@throws` where + appropriate. Test code does not require API documentation. +- If an assignment specifies a `-README` switch, it must print a brief, + formatted description that names the student and assignment, not merely + command usage. It must do no other work or error checking. If implemented + from a file, load that file as a Java resource rather than through a + relative runtime path. + +## Testing and validation + +- Write and maintain both unit and integration tests. Exercise every class + written for the project and aim for at least 75% instruction coverage. +- For Maven projects with the course grader profile, validate with + `./mvnw -Pgrader clean verify`. Do not delete, weaken, skip, or alter tests + merely to make a build pass. +- Use `InvokeMainTestCase`-style integration tests for command-line programs: + supply `main` arguments and verify captured standard output and standard + error. +- Do not put mutable non-`final` static fields in a class that contains + `main`; integration tests may invoke `main` repeatedly in one JVM. Do not + call `System.exit` from project code exercised by tests. +- When coverage needs investigation, inspect + `target/site/jacoco/index.html` after the grader build. + +## Collaboration and submission + +- Use the course scripts when relevant: `survey.sh` must run on a PSU MCECS + Linux machine and creates `me.xml`; `createStudentProject.sh` scaffolds new + assignments; `submit.sh ProjectN` submits work from PSU Linux. +- Keep commits small, meaningful, and authored by the student. Do not treat a + GitHub push as a submission; use the course-provided `submit.sh` process + when an assignment requires submission. +- When helping debug, ask for the command run, complete error text, observed + behavior, and expected behavior. Prefer explaining how to investigate over + guessing. +- If a submission needs a later fix, have the student branch from the submit + tag (for example `fix-Project1`) and push that branch rather than rewriting + history. diff --git a/README.md b/README.md index 8c76ce2..448f239 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Java CI with Maven](https://github.com/YourGitHubId/JoyOfCodingSummer2026/actions/workflows/maven.yml/badge.svg)](https://github.com/YourGitHubId/JoyOfCodingSummer2026/actions/workflows/maven.yml) +[![Java CI with Maven](https://github.com/YourGitHubId/JoyOfCodingWinter2027/actions/workflows/maven.yml/badge.svg)](https://github.com/YourGitHubId/JoyOfCodingWinter2027/actions/workflows/maven.yml) # Getting Started with The Joy of Coding with Java and Android @@ -71,7 +71,7 @@ developer"](https://education.github.com/pack) account that gives you free private repositories. Then [create a private GitHub repository from this "template" repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) for your source code for this course. (In this example, the -repository is named "JoyOfCodingSummer2026".) +repository is named "JoyOfCodingWinter2027".) Again, please ensure that all of your code for the assignments is in a **private** GitHub repository. GitHub makes it very easy for people to @@ -99,7 +99,7 @@ The following command lines assume that you are running in the directory created by cloning the repository. ```sh -$ cd JoyOfCodingSummer2026 +$ cd JoyOfCodingWinter2027 ``` ### How do I use the Java Development Kit? @@ -229,7 +229,7 @@ clone by adding the directory to git. ```sh $ ./mvnw clean # Remove files that shouldn't be committed to version control -$ cd .. # to JoyOfCodingSummer2026 directory +$ cd .. # to JoyOfCodingWinter2027 directory $ git add student $ git commit -m "Added source files for student project" ``` @@ -288,7 +288,7 @@ After `ssh`ing to one of the CS Department's Linux machines, you can make a clone of your GitHub repository using with: ``` -$ git clone https://github.com/YourGitHubId/JoyOfCodingSummer2026.git +$ git clone https://github.com/YourGitHubId/JoyOfCodingWinter2027.git ``` ## How do I submit my projects? @@ -328,6 +328,22 @@ You will also be asked to provide a rough estimate of the number of hours you sp optional information will be recorded and reported to future students in aggregate to give them an idea of how much time they should plan to spend on projects. The estimated hours you report will have no bearing on your grade. +Additionally, the `submit.sh` script will ask you to describe how you leveraged Artificial Intelligence (e.g. AI coding +assistants, chatbots) in the assignment. There are several predefined categories of AI usage for you to choose from, +and also you have the ability to provide your own description. + +```text +How would you describe your use of AI on this project? + 1. AI wrote the vast majority of the code + 2. AI reviewed the code I wrote and offered me suggestions for improvement + 3. AI researched answers to questions I had + 4. AI was not used + 5. Other +``` + +Your response to this question will have no bearing on your project grade. Student responses will be aggregated to +understand how AI is used today and how it might be expected to be used by future students. + The script may take a moment or two to zip the source files and email them to the Grader. You will receive a receipt email telling you which files were sent. @@ -437,8 +453,8 @@ As you create Maven projects in this repository, you may encounter warnings like ``` [WARNING] -[WARNING] Some problems were encountered while building the effective model for edu.pdx.cs.joy.whitlock:airline:jar:1.0.0 -[WARNING] 'parent.relativePath' of POM edu.pdx.cs.joy.whitlock:airline:1.0.0 (JoyOfCodingSummer2026/airline/pom.xml) points at edu.pdx.cs.joy.whitlock:JoyOfCodingSummer2026 instead of io.github.davidwhitlock.joy:joy, please verify your project structure @ line 3, column 11 +[WARNING] Some problems were encountered while building the effective model for edu.pdx.cs.joy.whitlock:apptbook:jar:1.0.0 +[WARNING] 'parent.relativePath' of POM edu.pdx.cs.joy.whitlock:apptbook:1.0.0 (JoyOfCodingWinter2027/apptbook/pom.xml) points at edu.pdx.cs.joy.whitlock:JoyOfCodingWinter2027 instead of io.github.davidwhitlock.joy:joy, please verify your project structure @ line 3, column 11 [WARNING] [WARNING] It is highly recommended to fix these problems because they threaten the stability of your build. [WARNING] @@ -457,7 +473,7 @@ When created, the `pom.xml` files for the projects specify a parent of _my_ top- joy io.github.davidwhitlock.joy - 1.2.4 + 1.3.1-SNAPSHOT ``` @@ -546,7 +562,7 @@ Running `mvn site` from the root directory of this repository will generate a website that provides lots of information (reports, etc.) about the Maven projects. Note that in order for your multi-project Maven site to generate correctly, the subprojects must specify that -their parent project is the `JoyOfCodingSummer2026` project in +their parent project is the `JoyOfCodingWinter2027` project in your group: ```xml @@ -589,7 +605,7 @@ You can open `target/staging/index.html` in your web browse to see what your site will look like. Verify that your website is available at a URL like: -https://yourgithubuser.github.io/JoyOfCodingSummer2026 +https://yourgithubuser.github.io/JoyOfCodingWinter2027 Using the `scm-publish:publish-scm` Maven plugin and a `gh-pages` branch to host your website is a great way to get started. You can also use the [configure-pages](https://github.com/marketplace/actions/configure-github-pages), diff --git a/createFirstProject.sh b/createFirstProject.sh index 033b410..abeda81 100755 --- a/createFirstProject.sh +++ b/createFirstProject.sh @@ -13,4 +13,4 @@ else fi fi -createProjectFromArchetype ${loginId} "airline" "2.2.6" +createProjectFromArchetype ${loginId} "apptbook" "2.2.7-SNAPSHOT" diff --git a/createKataProject.sh b/createKataProject.sh index b1bff3d..d1d67e1 100755 --- a/createKataProject.sh +++ b/createKataProject.sh @@ -15,4 +15,4 @@ fi projectName=$1 teamName=$2 -createProjectFromArchetype ${teamName} "kata" "2.2.7" ${projectName} +createProjectFromArchetype ${teamName} "kata" "2.2.8-SNAPSHOT" ${projectName} diff --git a/createKoansProject.sh b/createKoansProject.sh index ae58409..318895d 100755 --- a/createKoansProject.sh +++ b/createKoansProject.sh @@ -13,4 +13,4 @@ else fi fi -createProjectFromArchetype ${loginId} "java-koans" "2.2.9" "koans" +createProjectFromArchetype ${loginId} "java-koans" "2.2.11-SNAPSHOT" "koans" diff --git a/createRESTProject.sh b/createRESTProject.sh index 8b97250..94ec20b 100755 --- a/createRESTProject.sh +++ b/createRESTProject.sh @@ -13,4 +13,4 @@ else fi fi -createProjectFromArchetype ${loginId} "airline-web" "3.1.0" +createProjectFromArchetype ${loginId} "apptbook-web" "3.1.1-SNAPSHOT" diff --git a/createStudentProject.sh b/createStudentProject.sh index a65c72d..90056dc 100755 --- a/createStudentProject.sh +++ b/createStudentProject.sh @@ -13,5 +13,4 @@ else fi fi -createProjectFromArchetype ${loginId} "student" "2.3.6" - +createProjectFromArchetype ${loginId} "student" "2.3.7-SNAPSHOT" diff --git a/pom.xml b/pom.xml index ae971c2..435d4be 100644 --- a/pom.xml +++ b/pom.xml @@ -12,28 +12,28 @@ accordingly joy io.github.davidwhitlock.joy - 1.3.0 + 1.3.1-SNAPSHOT edu.pdx.cs.joy.YourUserId JoyOfCoding 1.0.0 pom - JoyOfCodingSummer2026 - Source code written in the Summer 2026 offering of The Joy of Coding - http://YourGitHubUserInLowerCase.github.io/JoyOfCodingSummer2026 + JoyOfCodingWinter2027 + Source code written in the Winter 2027 offering of The Joy of Coding + http://YourGitHubUserInLowerCase.github.io/JoyOfCodingWinter2027 - 2026 + 2027 Portland State University http://www.pdx.edu github - https://github.com/YourGitHubUser/JoyOfCodingSummer2026/issues + https://github.com/YourGitHubUser/JoyOfCodingWinter2027/issues @@ -76,7 +76,7 @@ accordingly maven-site-plugin - scm:git:git@github.com:YourGithubUser/JoyOfCodingSummer2026.git + scm:git:git@github.com:YourGithubUser/JoyOfCodingWinter2027.git @@ -92,7 +92,7 @@ accordingly - scm:git:git@github.com:YourGithubUser/JoyOfCodingSummer2026.git + scm:git:git@github.com:YourGithubUser/JoyOfCodingWinter2027.git @@ -102,7 +102,7 @@ accordingly gh-pages GitHub Pages - scm:git:git@github.com:YourGithubUser/JoyOfCodingSummer2026.git + scm:git:git@github.com:YourGithubUser/JoyOfCodingWinter2027.git diff --git a/src/site/site.xml b/src/site/site.xml index 07bc899..fbf18e5 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -17,7 +17,7 @@ true - YourGitHubUser/JoyOfCodingSummer2026 + YourGitHubUser/JoyOfCodingWinter2027 right black diff --git a/submit.sh b/submit.sh index 8ca7137..2e72b46 100755 --- a/submit.sh +++ b/submit.sh @@ -29,16 +29,16 @@ elif [[ "$project" == "koans" ]]; then directory="koans" mavenGoals="clean exec:java" -elif [[ "$project" == "Project4" ]]; then - directory="airline-web" - elif [[ "$project" == "Project5" ]]; then - directory="airline-android" + directory="apptbook-web" + +elif [[ "$project" == "Project6" ]]; then + directory="apptbook-android" submitClass="SubmitAndroidProject" srcDirectory="." else - directory="airline" + directory="apptbook" fi if [ $# -gt 1 ]; then