docs: Introduce new concept for TemporalAdjusters #2944
Conversation
Introduces the `Temporal Adjusters` concept, including an overview, examples, and links for Java's `TemporalAdjuster` and `TemporalAdjusters` utilities. Updates `config.json` to include the concept and a new exercise, "Meetup," with relevant prerequisites.
Simplify the introduction and examples for `TemporalAdjusters` to improve clarity and focus on practical use cases. Removed redundant examples and reorganized sections to prioritize key adjusters like ordinal days and "teenth" date calculations. Enhanced consistency and readability across code snippets and explanations.
Adjusted the `blurb` text for clarity and reformatted the `authors` field for improved readability. These changes maintain consistency with JSON coding standards and enhance the file's maintainability.
Replaced asterisks with dashes for consistency in list formatting and added blank lines for better readability. These changes improve the overall structure and clarity of the documentation.
Standardize heading levels for consistency and readability. Changed `###` to `##` in multiple sections to align with the document's structure. No content modifications were made.
The links to LocalDate and DayOfWeek documentation were unused and have been removed to improve clarity and maintainability. This helps keep the documentation clean and focused.
Relocated the `meetup` exercise and updated its structure to align with the concept track. Adjusted paths, references, and configuration files accordingly to reflect this transition. No functional changes to the implementation or tests were made.
The "Meetup" exercise entry has been deleted, including its slug, name, uuid, practices, prerequisites, and difficulty level.
Introduce `introduction.md.tpl` and `hints.md` for the Meetup exercise to guide learners. The hints provide detailed steps on working with `LocalDate` and `TemporalAdjusters` for date manipulations.
Added the "exemplar" key to the config.json for better exercise organization. Also fixed the missing newline at the end of the hints.md file to ensure proper formatting.
The `tests.toml` file and specific keys in `config.json` for the meetup exercise have been removed. These changes clean up outdated metadata and streamline the exercise configuration.
Introduces learning objectives, out-of-scope topics, concepts, prerequisites, and analyzer rules for the exercise. Clarifies focus on `TemporalAdjusters` and proper usage of `java.time` API while providing guidance for evaluations in the analyzer.
Updated `config.json` to include 'editor' paths for 'meetup' and adjusted `settings.gradle` to include the concept version while removing the practice version. This aligns with the intended migration from a practice exercise to a concept exercise.
|
Ah, I noticed you've moved the meetup exercise to a concept exercise. We shouldn't be doing that because it is a practice exercise, with a problem spec in the problem-specifications repo (so the tests are shared across the tracks). Instead, we should come up with another concept exercise to introduce temporal adjusters. For the concept exercise, we'll need to choose a background story. For example, we're using Booking Up For Beauty for Local Date/Time. For temporal adjusters, C# also uses Beauty Salon Goes Global - we could probably do the same. Alternatively, we could also look through the list to see what other stories are used. We should also add |
| // => 2024-08-26 | ||
| ``` | ||
|
|
||
| ## Finding Relative Occurrences ("Teenth" dates) |
There was a problem hiding this comment.
I think this is a left over from writing for the "meetup" exercise? Since this is an introduction to the temporal adjusters concept, I think we can copy the Relative Adjustments (Next/Previous) content from the about.md here.
Thank you for your suggestion. To be honest, I was also thinking about a special exercise. It take some time :) |
pull request
Description
This PR introduces a new concept, "TemporalAdjusters", to the Java track's syllabus.
Motivation:
It has been observed (e.g., during mentoring for the
Meetupexercise) that many students are unfamiliar with thejava.time.temporal.TemporalAdjusterinterface and the associatedTemporalAdjustersutility class. This often leads to complex manual date calculations instead of leveraging these powerful and idiomatic standard library features.Solution:
This PR adds a dedicated concept to explain
TemporalAdjusters, covering:.with()method.TemporalAdjustersclass (e.g.,dayOfWeekInMonth,lastInMonth,nextOrSame).java.time.The following files have been created for this concept:
concepts/temporal-adjusters/about.mdconcepts/temporal-adjusters/introduction.mdconcepts/temporal-adjusters/links.jsonUUID:
cc7a06d1-ddb3-4722-88a5-f762254d664eThe concept has also been added to the track's main configuration file using the UUID above.
Goal:
By introducing this concept, we aim to guide students towards using
TemporalAdjustersearlier, enabling them to write more idiomatic and robust solutions for date-related exercises.Closes #2937
Reviewer Resources:
Track Policies