Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.
36 changes: 26 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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?
Expand Down Expand Up @@ -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"
```
Expand Down Expand Up @@ -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?
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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]
Expand All @@ -457,7 +473,7 @@ When created, the `pom.xml` files for the projects specify a parent of _my_ top-
<parent>
<artifactId>joy</artifactId>
<groupId>io.github.davidwhitlock.joy</groupId>
<version>1.2.4</version>
<version>1.3.1-SNAPSHOT</version>
</parent>
```

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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),
Expand Down
2 changes: 1 addition & 1 deletion createFirstProject.sh
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ else
fi
fi

createProjectFromArchetype ${loginId} "airline" "2.2.6"
createProjectFromArchetype ${loginId} "apptbook" "2.2.7-SNAPSHOT"
2 changes: 1 addition & 1 deletion createKataProject.sh
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@ fi
projectName=$1
teamName=$2

createProjectFromArchetype ${teamName} "kata" "2.2.7" ${projectName}
createProjectFromArchetype ${teamName} "kata" "2.2.8-SNAPSHOT" ${projectName}
2 changes: 1 addition & 1 deletion createKoansProject.sh
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ else
fi
fi

createProjectFromArchetype ${loginId} "java-koans" "2.2.9" "koans"
createProjectFromArchetype ${loginId} "java-koans" "2.2.11-SNAPSHOT" "koans"
2 changes: 1 addition & 1 deletion createRESTProject.sh
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ else
fi
fi

createProjectFromArchetype ${loginId} "airline-web" "3.1.0"
createProjectFromArchetype ${loginId} "apptbook-web" "3.1.1-SNAPSHOT"
3 changes: 1 addition & 2 deletions createStudentProject.sh
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,4 @@ else
fi
fi

createProjectFromArchetype ${loginId} "student" "2.3.6"

createProjectFromArchetype ${loginId} "student" "2.3.7-SNAPSHOT"
18 changes: 9 additions & 9 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,28 @@ accordingly
<parent>
<artifactId>joy</artifactId>
<groupId>io.github.davidwhitlock.joy</groupId>
<version>1.3.0</version>
<version>1.3.1-SNAPSHOT</version>
</parent>
<groupId>edu.pdx.cs.joy.YourUserId</groupId>
<artifactId>JoyOfCoding</artifactId>
<version>1.0.0</version>

<packaging>pom</packaging>
<name>JoyOfCodingSummer2026</name>
<description>Source code written in the Summer 2026 offering of The Joy of Coding</description>
<url>http://YourGitHubUserInLowerCase.github.io/JoyOfCodingSummer2026</url>
<name>JoyOfCodingWinter2027</name>
<description>Source code written in the Winter 2027 offering of The Joy of Coding</description>
<url>http://YourGitHubUserInLowerCase.github.io/JoyOfCodingWinter2027</url>

<modules>
</modules>

<inceptionYear>2026</inceptionYear>
<inceptionYear>2027</inceptionYear>
<organization>
<name>Portland State University</name>
<url>http://www.pdx.edu</url>
</organization>
<issueManagement>
<system>github</system>
<url>https://github.com/YourGitHubUser/JoyOfCodingSummer2026/issues</url>
<url>https://github.com/YourGitHubUser/JoyOfCodingWinter2027/issues</url>
</issueManagement>
<licenses>
<license>
Expand Down Expand Up @@ -76,7 +76,7 @@ accordingly
<plugin>
<artifactId>maven-site-plugin</artifactId>
<configuration>
<topSiteURL>scm:git:git@github.com:YourGithubUser/JoyOfCodingSummer2026.git</topSiteURL>
<topSiteURL>scm:git:git@github.com:YourGithubUser/JoyOfCodingWinter2027.git</topSiteURL>
</configuration>
</plugin>
<plugin>
Expand All @@ -92,7 +92,7 @@ accordingly
</build>

<scm>
<connection>scm:git:git@github.com:YourGithubUser/JoyOfCodingSummer2026.git</connection>
<connection>scm:git:git@github.com:YourGithubUser/JoyOfCodingWinter2027.git</connection>
</scm>
<distributionManagement>
<snapshotRepository>
Expand All @@ -102,7 +102,7 @@ accordingly
<site>
<id>gh-pages</id>
<name>GitHub Pages</name>
<url>scm:git:git@github.com:YourGithubUser/JoyOfCodingSummer2026.git</url>
<url>scm:git:git@github.com:YourGithubUser/JoyOfCodingWinter2027.git</url>
</site>
</distributionManagement>

Expand Down
2 changes: 1 addition & 1 deletion src/site/site.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
</googleSearch>
<sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
<gitHub>
<projectId>YourGitHubUser/JoyOfCodingSummer2026</projectId>
<projectId>YourGitHubUser/JoyOfCodingWinter2027</projectId>
<ribbonOrientation>right</ribbonOrientation>
<ribbonColor>black</ribbonColor>
</gitHub>
Expand Down
10 changes: 5 additions & 5 deletions submit.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading