[UserStory] Readme clarity, order of instructions for local install

[elmattes]

User Story

Essential components

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

Story

As a user or potential contributor I want to be able to open the Github page and follow the readme instructions from top to bottom to install and run the project on a local machine so that other users can install the project with ease.

Acceptance Criteria

I propose the following order for the readme:

1. Image lab description
2. Contents
3. Build instructions -> Move the following instructions beneath the Build category in this order: -> 1. Build System Requirements -> 2. Creating an executable jar -> 3. Use from command line -> 4. Using gradle / resources
4. License
5. Project website

Supporting Information

At current, the instructions for install are out of order. Gradle must be installed first before you can create an executable jar or compile and run from the command line, these steps should directly follow gradle install. Resources for gradle use should be below the instructions required to install / build / run the project locally. For a new user of the project, this should put the install steps in order and provide more clarity for the user.

Dependencies

Depends On

117 , #118

[jody]

The objective of making the README information more effective is definitely worth pursuing!

Consider that an end-user (educator or student) probably just wants to know how to use the product rather than how to build it. For them, having the "use from command line" or "use as a BlueJ project" should appear first. A maintainer may place a higher priority on knowing how to build the product. It's unclear that any specific ordering is "best" for all stakeholders.

On the other hand, all stakeholders are likely to benefit from an overview of what is contained in the README and some form of quick access for them to go directly to the section(s) of interest to them. This suggest something like a "table of contents" set of links appearing just under the current one-line description.

Also very likely to be helpful for all stakeholders would be revising the text of the headings and subheadings so the those headings (and associated table of contents links) identify the content of each section in language appropriate to the reader.

[elmattes]

I've added a table of contents as discussed, along with changes to the order to bring the BlueJ and command line instructions next to each other. A few typos have been fixed and some changes made to readability. Here's the current readme I propose as a change (make note that the table of content links do not work in this comment form, but they do work in my cloned repository which you can reference here: https://github.com/ematteso/imagelab ):

ImageLab

ImageLab is a framework that allows students to develop image modification processors (filters) and to experience the results visually and aurally. This project can be ran as a BlueJ Project, directly from the command line, or built with a gradle wrapper.

Table of Contents

• Repository Contents
• BlueJ Instructions
• Command Line Instructions
• Build Instructions
• License

Repository Contents

• The imagelab and sound packages may be provided in an imagelab.jar file.
• The imagelab.jar file also includes the class Run with a public static void main method in the unnamed package, used to facilitate running the ImageLab application.
• The filter package is generally provided as a folder with source (.java) and compiled (.class) files, with the source versions serving as examples for students to create their own filters.
• A sample set of images are provided in an "images" directory.

BlueJ Instructions

Install BlueJ for your operating system

1. Clone the ImageLab repository to your local machine.
2. Run BlueJ
3. Select Project in the BlueJ menu > Open Project
4. Select the root folder of the cloned ImageLab repository.
5. Right click the box titled "Run" > Select "void main(String[] args)"
6. Hit "OK", or enter on your keyboard.

At this point, ImageLab should open in a seperate GUI window.

Use From Command Line:

1. Open command line and change directory to the ImageLab root folder. If you have not cloned the repository, do so and change directory to the root.
2. In your file explorer, navigate into the ImageLab root folder > Filters. Make sure there is at least one filter inside. If the filter source code has not compiled, issue the command: javac -cp .:imagelab.jar filters/*.java
3. Run the ImageLab application using the command
   java -cp ".:imagelab.jar" Run
   (Note that on Windows platforms, the ":" character in the classpath must be changed to the ";" character.)

Build Instructions

Build System Requirements

• Install Gradle
  • Gradle is the tool used in this repository for automation of the build. Please visit https://gradle.org/ for specific installation instructions.

Creating an executable jar file

The project is set up to use gradle wrapper to create the jar file.

1. Change the working directory to be the project's root directory.
2. Execute the command ./gradlew build A. This will build/rebuild the jar file and required dependencies.
3. The new jar file will be named "imagelab.jar" and located in the project's root directory.

More information on gradle can be found here and more information on the gradle wrapper can be found here.

If there is no automated build environment set up, the jar file can be created using the jar command.

1. Change the working directory to be the project's root directory.
2. Execute the command javac Run.java to compile the Run.java file.
3. Execute the command javac */*.java to compile/recompile the files in packages imagelab, sound, and filters.
4. In the root directory execute the command echo Main-Class: Run > MANIFEST.MF to create the manifest file for the jar.
5. Create the jar using the command jar cfm imagelab.jar MANIFEST.MF *.class sound/*.class imagelab/*.class
6. The new jar file will be named "imagelab.jar" and located in the project's root directory.

More information on creating the jar can be found here and more information about java commands can be found here.

An executable jar file can also be created within most IDEs.

Using Gradle

To build the project from a copy of the repository use the command:
./gradlew build

Useful Commands

• Display the full list of tasks that can be excecuted
  • ./gradlew tasks --all
• Run the program
  • ./gradlew run
• Compile the main java source
  • ./gradlew compileJava
• Delete the build directory
  • ./gradlew clean
• Assemble the main classes
  • ./gradlew classes
• Assemble and test the project
  • ./gradlew build
• Assemble the test classes
  • ./gradlew testClasses
• Generate checkstyle reports
  • ./gradlew checkstyle
• Run unit tests
  • ./gradlew test
• Compile unit tests
  • ./gradlew compileTestJava
• Run all checks
  • ./gradlew check

Resources and References

https://gradle.org/guides/

License

ImageLab is a framework for student exploration of image processing.
Copyright (C) 2016,2019 by Aaron Gordon & Jody Paul
The software comes with ABSOLUTELY NO WARRANTY.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/

---

Project Website: https://metrocs.github.io/imagelab/

[jody]

I think we need to distinguish between the "use" of ImageLab by students and educators (running the product) from the "development" of ImageLab by developers (maintaining the product). These are two different groups of stakeholders.

The information page for users (students and educators) is found at this URL: https://metrocs.github.io/imagelab/

Users should not need to go to the GitHub repository (unless they want to see the project from a developer/maintainer perspective.)

Since users may inadvertently go to the repository directly, perhaps the pointer to the Project Website should be moved to the top part of the README.md with labeling that directs people looking for information about "using" ImageLab to that website.

[jody]

The table of contents still makes sense for the repository README, focused on the developer perspective.

[elmattes]

Makes sense to move the website to the top of the ReadMe, and I've made the appropriate changes.

Then my question for you is do you think that there needs to be some kind of additional clarification to distinguish between "use" and "development" in your ReadMe?

[jody]

In preparation for one or more pull requests, I recommend splitting this into multiple user stories/issues, such as:

As a user I want my landing on the GitHub repository page with README displayed to tell me how to get and use the product so that I can use the product and do so appropriately

As a developer I want to be able to learn how to build the product so that I can make appropriate contributions to the project

[jody]

Notes: We agreed to create two new issues (User Stories) and link them as "Depends on" of this issue. I've updated the structure of this issue with the project's format for a Dependencies section.

[elmattes]

After discussing in person, I've made two new user stories that this issue depends on. All three have been updated accordingly with linked dependencies/dependants.