[UserStory] Project should document build requirements for Java and Gradle

[jreiser1]

User Story

Essential components

• Title describes the story
• Stakeholder type is identified
• Outcome is described
• Rationale is explicit
• Acceptance criteria are verifiable and from the perspective of the stakeholder

Story

As a developer
I want information about required versions of development tools and components to be included in the developers' documentation
so that the setup process can be completed with easy-to-find guides and information

Acceptance Criteria

• Requirements for matching JDK version used to build the product (extension) with the target version(s) of BlueJ is included in a new file called BuildInformation.md, which shows where to find the associated specific information.
• Information about using the provided Gradle wrapper is included in BuildInformation.md
• README.md contains a link to BuildInformation.md

Supporting Information

• build.gradle references a requirement for JDK version 11.x
• Gradle wrapper is supplied with project

Dependencies

Depends On

#8 Document project conventions

[jody]

I recommend rewriting the desired outcome ("I want") to clarify what the developer wants rather than specifying a particular solution. For example, "I want information about required versions of development tools and components to be included in the developers' documentation". That allows for solutions that put such information in a location other than "conventions". ("Version" information seems like it would change more rapidly than "conventions" ought to.)

I can see another aspect, which is that the location of that information should be "obvious", thus easy to find.

The acceptance criteria can embody the specifics.

Please update the User Story.

[jreiser1]

Updated. Doc fixes are in the works so we should have a pull request coming soon.

[jody]

Why is DevelopmentConventions.md the right place to put tool version requirement information? That does not seem intuitive.

[jreiser1]

DevelopmentConventions.md already contains information about the tools which are used in the development environment for this project. The Build Environment section states "The following tools are established as comprising and contributing to the build environment for the QT4BJ project." so I thought that would be a good place to list tool version requirements.

[jreiser1]

The Project-Specific Conventions section under the Coding Conventions Guide section of DevelopmentConventions.md might be a good place to put this info as well.

[jody]

Thanks for the comments. I can appreciate that version numbers could be associated with each tool in DevelopmentConventions.md.

My concern is with ongoing maintainability. A desirable solution is for there to be a single location where version information is maintained. When the version changes, the update is made in that one location.

Any part of the process that depends on that information should get it from that one place.

Is there a way to have this information stored in a way that can be used by the build process as well as serving as documentation? How about something similar to a "properties" file?

[jody]

The acceptance criteria needs to be reworked before this is ready for development.

[jreiser1]

I have reworked the Acceptance Criteria and Title of the issue

[jody]

Looked good. I did some word-smithing of the Acceptance Criteria. I think it's ready to go.

[jody]

Will move this into "In Progress".