---
# System prepended metadata

title: Revision Plan

---

# Revision Plan
## Introduction
Milestone 3 provided us with plentiful of valuable criticism which we turned into an actionable revision plan. Our review plan further includes how we plan on processing feedback from Milestone 1 and 2.

Our colleagues have communicated with us the ways in which our AD fails to properly inform the readers. Our mission is to showcase that Gradle meets its functional and non-functional requirements. The functional requirements emphasized in our AD are partially detailed in the [important scenarios](https://hackmd.io/2sH_s1J1SeaK5QHdD8fL6w) section. 

This document highlights the important feedback and the actions taken to address the criticism. We also provide justifications for our actions which should prove to be insightful to readers. The justifications will detail our reasoning behind the actions taken, such as the tradeoffs we had to consider, etc...

## Table of contents
| Section |
| -- |
| [Context View](#Context-View) |
| [Stakeholders](#Stakeholders) |
| [Functional View](#Functional-View)<br>* [Component Diagram and Element Catalogue](#Component-Diagram-and-Element-Catalogue)<br>* [Sequence Diagram](#Sequence-Diagram) |
| [Information View](#Information-View)<br>* [Metadata Model](#Metadata-Model)<br>* [Dynamic Information Model](#Dynamic-Information-Model) |
| [Global AD Feedback](#Global-AD-Feedback)|

# Context View
### 1.
#### Criticism
What’s the difference between “Dependency Repository” and “Repository”?
#### Decision
Completely address
#### Justification for decision
We were too specific in our initial context view. We wanted to differentiate between the repositories which contain plugins and which contain source code dependencies. However, we now recognize that the distrinction is not necessary, especially not within in the context view.
#### Changes
We will merge the two terms into a singular external element called “Repository”.

---
### 2.
#### Criticism
Varying fonts and small label margins make the diagram harder to read and "crowded"
#### Decision
Completely address
#### Justification for decision
In retrospect, we recognize that the varying font sizes clutter the diagram. We used varying font sizes to highlight elements of varying importance, however we believe that readibility is more important.

#### Changes
We will pick a uniform font size for our models (except for the main element: Gradle).

---
### 3.
#### Criticism
View lacks depth and refinement: the information is hard to parse for a reader unfamiliar with the system, and entities should be described more thoroughly
#### Decision
Completely address
#### Justification for decision

Gradle is an extremely complex system, we initially dove too deep in the code and drew a blurry line between software implementation and software architecture. We believe that a healthy level of abstraction should be present in our views.

#### Changes

We will add a glossary of terms and abstract some of the more unclear aspects of Gradle. We will put useful, yet unecessary detail into an appendix.

---
# Stakeholders

### 4.
#### Criticism
Some groups of stakeholders can have varying power/interest
#### Decision
Partially address
#### Justification for decision
We think that most stakeholders have similar power/interest, we do agree that some stakeholders (notably project developers) should have varying power/interest.

#### Changes
We will modify the power/interest of some stakeholders in our stakeholder such that the "range" of power/interest is more detailed.

---
### 5.
#### Criticism
Stakeholders somewhat user- and developer-focused
#### Decision
Ignore
#### Justification for decision
Gradle as a software is very much a user- and developer-focused tool. Users/Developers are our highest priority stakeholders  Therefore, we believe that the focus on our highest priority stakeholders is appropriate.

#### Changes
N/A

---
### 6.
#### Criticism
Why do Android developers have higher power than other project developers or development tool developers?
#### Decision
Partially address
#### Justification for decision
We added this as we felt that their connection with Google and their ecosystem made Android developers more important. However, we now see how specifying Android Developers leads to confusion. Especially since we [do not specify Google as a stakeholder](https://hackmd.io/RTlC56qhToG6Qej3yxdeiA#Note).
#### Changes
We will remove Android Developers since they belong to Project Developers.

---
### 7.
#### Criticism
List of stakeholders could be better sorted
#### Decision
Completely address
#### Justification for decision
We agree that a sorting the list of stakeholders by priority is good and does not have any downside (compared to our current arrangement).

#### Changes
The stakeholders will be sorted in descending order by priority (highest priority on top). Priority is subjectively derived from the power/interest metric.

---
# Functional View

### 8.
#### Criticism
No architectural style or pattern
#### Decision
Completely address
#### Justification for decision
We completely forgot to mention architectural styles and software design patterns. 

#### Changes
We will add information in the appendix relating to the microkernel architeral style Gradle is based on, we will also add an entry comparing Tasks to the command design pattern. We will reference the appendix from the appropriate views.

---
## Component Diagram and Element Catalogue

### 9.
#### Criticism
There is something off-putting about Task providing an executeTask() interface. A Task sounds like a form of Command pattern; is there some sort of Processor somewhere to execute it?
#### Decision
Partially address
#### Justification for decision
Tasks can be seen as containers for Actions, actions themselves can be executed. We believe that the ExecuterSystem currently is currently too abstract which might be the cause of the confusion.

#### Changes
We will address this when we rewrite our functional view. We believe our current functional view is lacking and confusing. Our new view should clearly distinguish between the initialization system and the execution system (responsible for executing tasks).

---
### 10.
#### Criticism
It is also a little confusing to have object names for interfaces(e.g., ActionBuilder.) If the object is not important enough to be a component, perhaps it should be abstracted as a function (e.g., "buildAction")? If it is important, perhaps it can be modeled as a connector?
#### Decision
Completely address
#### Justification for decision
The criticism is correct in that the way we named interfaces added unnecessary complexity. We tried to be too specific in our original views, we believe that we should allow abstractions and put less emphasis on the Gradle's current software implementation.
#### Changes
Interfaces will be renamed and absracted using "method names". We will also reorganize the views to be more readable.

---
### 11.
#### Criticism
There is an inconsistency in the notation of the interfaces, with the “()” at the end of some interfaces being used to reference an actual method in the code. This is never explained in the view. I would either include a definition in the diagram (i.e., through a legend) or remove the “()” and reference the method (including the class/code line it comes from) in the element catalogue description of the interface.
#### Decision
Completely address
#### Justification for decision
We ignored the implications of using parenthesis ("method calls") in only some of our interfaces, we agree that this can be misleading and confusing.

#### Changes
We will ensure that our interface names are consistent when rewriting our views.

---
### 12.
#### Criticism
The main(args) provided interface is not in the element catalogue. I am not sure what this interface does, or who uses it?
#### Decision
Ignore
#### Justification for decision
Since our AD focuses on the developer stakeholders, we believe that main(args) is commonly used to denote a program's entry point. We will not address this, we believe the use of main(args) is appropriate and not misleading.
#### Changes
N/A

---
### 13.
#### Criticism
What is the role of the Daemon Server? I am unsure if the Daemon Server is an external element? When discussing the DaemonClient element you mention that it sends messages to the server, but there is no interface provided by the client to access the server nor an external element present in the diagram.
#### Decision
Completely address
#### Justification for decision
The daemon is used to ensure Gradle meets its performance quality property. We believe our current explanations are insuffcient for such a crucial architectural element.
#### Changes
when applying the Performance perspective on our views, more notably the functional view, we will make sure to better detail the Daemon.

---
### 14.
#### Criticism
The subsystem of plugins seems incomplete. For example, in the element catalogue, you say “The JavaPlugin applies the BasePlugin” which seems as though there should be an interface linking JavaPlugin and BasePlugin or two distinct interfaces provided to the project aside from the provided PluginManager. Specifically, the PluginManager does not appear to accommodate this behaviour, as it only keeps track of plugins applied. Overall, more clarity is needed on the interactions between plugins.
#### Decision
Completely address
#### Justification for decision
We attempted to give example of plugins (BasePlugin, JavaPlugin, ...) by showing plugin as a subsytem in our functional view. We recognize that this is confusing since it not an appropriate way to model things.

#### Changes
The plugin interface will be renamed to be more explicit in the functionality a Plugin provides to the Project. We will model Plugin as a component rather than a subsytem, therefore we will remove the examples/implementations from our diagram.

---
### 15.
#### Criticism
In the element catalogue, specifically in the ExecuterSystem, you mention something called a context. It is brought up at other times, and it is mentioned in the sequence diagram. However, I do not understand what a context is, a clearer definition needs to be provided.
#### Decision

#### Justification for decision

The ExecuterSystem was originally used to combine the initialization step of Gradle's build lifecycle and the execution step. In retrospect, we recognize that this is very confusing and unecessary. The "context" is not architecturally significant. We were simply answering our critics questions relating to Gradle's software implementation.

#### Changes

We will split the ExecuterSystem in two, the part responsible for the initialization of Gradle (Initializer) and the part responsible for the execution of tasks (Execution subsystem).

We will also model the components responsible for Gradle's initialization, configuration and execution in seperate models as subsystems. This will allow for clearer and more concise views. 

We do not believe that detailing the components belonging to the execution subsystem is important (such as the TaskTree or ActionExecutor). Therefore we will provide an explanation of the execution system's responsibilities without detailing its inner workings.

---
### 16.
#### Criticism
In the discussion, you mention plugin component will add tasks to the task component. However, there is no interface provided to perform this process.
#### Decision
Partially address
#### Justification for decision
The project does not add tasks to the Task component. It adds tasks to the project.
#### Changes
Renaming the interface between Plugin and Project will hopefully clarify this.

---
### 17.
#### Criticism
In the Component Diagram, both ActionManager and Daemon used BuildActionExecutor interface provided by ExecuterSystem. In the discussion, you mention Daemon is a safe way to execute the thread. However, this is not included in the element catalogue.
#### Decision
Completely address
#### Justification for decision
We recognize that we did not properly detail the Daemon in our AD.

#### Changes
We will better detail the Daemon in our functional view's element catalogue.

---
### 18.
#### Criticism
Skips over potentially relevant details, e.g., Ivy (add reference?) 
#### Decision
Partially address
#### Justification for decision

We feel that going into deeper detail about the types of artifacts accepted is not relevant to the architecture of our system so we opt to just remove references to the types of accepted artifacts.

#### Changes

We will modify our context view by encapsulating all types of repositories under "Source".

---
## Sequence Diagram

### 19.
#### Criticism
There is no justification for why this sequence diagram is included in the functional view. What does it add to the view? What does it enlighten about the system? Why did you choose to show this sequence diagram and not others? It is important to tie back to a defined scope (functional capabilities) to justify why you are limiting to this sequence diagram. Why not show different versions of building?
#### Decision
Completely address
#### Justification for decision

We recognize that we did not properly explain why we chose our sequence diagram and that our choice was questionable.

#### Changes

We will add more insightful sequence diagram(s). We will reconsider whether the current diagram is still needed once we have reworked our functional view. We will remove it if it is not.

---
### 20.
#### Criticism
There are no callbacks in the sequence diagram. We recommend that callbacks should be included to describe where the method ends (or if any information is returned or not). If no callbacks are included, a short justification in the description of the diagram would help justify this decision and avoid any confusion.
#### Decision

Ignore

#### Justification for decision

We will continue to model callbacks only when necessary. We believe our sequence diagram does not have to showcase "void" or architecturally insignifcant callbacks.

#### Changes

N/A

---
### 21.
#### Criticism
There are no clear links between the interfaces and the methods on the calls (arrows). Upon questioning, we determined that they are abstractions of a series of methods in the code, which are a part of the interface. It would be nice if this was clarified.
#### Decision

Partially address

#### Justification for decision

We believe that this confusion comes from using Java-like interface names in the component diagram (e.g "PluginManager" but we use a "managePlugins()" method in the sequence diagram).

#### Changes

We believe that after reworking our component diagram, the method names will be clearer.

---
### 22.
#### Criticism
In the description of the sequence diagram, you mention that the sequence diagram is: “a build action on a Gradle Project”. At the start of the view, you refer to a “build task”. Are a build action and a build task the same thing? Clearer language/consistency would be appreciated. This also loops back into the definitions of Task & Action (see global points below.)
#### Decision
Completely address
#### Justification for decision
We recognize that we did not differentiate between a Task, Build, and an Action. Since all three are "conceptually interconnected", we find the confusion reasonable.
#### Changes
We will include a glossary to define commonly used terms.

---
### 23.
#### Criticism
What triggers the start of the sequence diagram? In other words, who sends the launch(args) call? Is it a user or is it triggered by a system event?
#### Decision
Ignore
#### Justification for decision
We believe that this is already shown in the context view (the developers use Gradle). We do not believe that showing that "IDE" or "CLI" can be the entry points is architecturally signifcant.

#### Changes

N/A

---
# Information View

### 24.
#### Criticism
The Introduction of the Information view mentions Gradle being concerned with some source files. While we understood from the presentation that this notably includes the build.gradle file, there was initially some confusion as to which files were being referenced; this could be clarified in the AD.
#### Decision
Completely address
#### Justification for decision
We recognize that our information view is confusing, the mapping between configuration objects and files should be clear and explicit.
#### Changes
We will rewrite the information view to describe Gradle's elements which relate to its configurability rather than presenting a nebulous view of all the information that Gradle processes.

---
### 25.
#### Criticism
View lacks introduction/orientation to understand what's going on
#### Decision
Completely address
#### Justification for decision

We recognize our AD lacks refinement and organization.

#### Changes
We will completely reorganize our AD and add introductions, context and orientation where necessary.

---
## Metadata Model

### 26.
#### Criticism
Why is ArtifactRepository's cardinality one to many? This suggests that an External Source (which we understand is a library dependency such as Apache Commons Math) can be managed by multiple ArtifactRepository objects. Is this true?
#### Decision
Partially address
#### Justification for decision
The metadata model was not insightful with regards to how Gradle meets its functional requirements or achieves its desired quality properties.

#### Changes
We will no longer be using a metadata model. This will no longer be an issue.

---
### 27.
#### Criticism
The nature of the association between PublishedArtifact and File, ie that the latter is a persistent representation of the former, could be specified; otherwise it might be interpreted as PublishedArtifact using data contained in File in some way.
#### Decision
Partially address
#### Justification for decision
We will completely rewrite our information view to focus on Gradle's configuration. A PublishedArtifact is not a configuration object.

#### Changes
Published artifact will no longer be addressed in the view.

---
### 28.
#### Criticism
Somewhat related to the term Source code, but perhaps Task could be added to the diagram. It is not necessarily that obvious that Tasks are defined in the build.gradle (also, perhaps this association could be added in the dynamic info model.) (Also also, since tasks can alternatively be defined in plugins, perhaps it is worth adding Plugin to the model as well.)
#### Decision
Completely address
#### Justification for decision
We recognize that our view overlooked the location and strucutre of the data defining task behavior.
#### Changes
We will write a new view that shows how tasks can be defined in the build.gradle file or applied added to a project via plugins.

---
## Dynamic Information Model

### 29.
#### Criticism
This may be a problem on Gradle's side, but what's the point of making Services singletons if they are accessed via a ServiceRegistry? It may be worth checking whether Services are actually singletons.
#### Decision
Partially address
#### Justification for decision
In restrospect, we believe that the ServiceRegistry is an insignificant implemenation detail.

#### Changes
The ServiceRegistry will be removed from the information view.

---
### 30.
#### Criticism
At face value, a Service sounds like a functionality provider, a black box that takes input and emits output; how does it contribute to an information view?
#### Decision
Partially address
#### Justification for decision
In restrospect, we believe that the ServiceRegistry is an insignificant implemenation detail.
#### Changes
The ServiceRegistry will be removed from the information view.

---
### 31.
#### Criticism
What do Services do? We understand they may cover a wide range of functionality, but a few examples could be helpful.
#### Decision
Partially address
#### Justification for decision
In restrospect, we believe that the ServiceRegistry is an insignificant implemenation detail.
#### Changes

The ServiceRegistry will be removed from the information view.

---
### 32.
#### Criticism
This may or may not be relevant, but perhaps fields could be added to some of the components? It may help communicate the data contained in, and purpose of, components like Task and Plugin.
#### Decision
Ignore
#### Justification for decision
The information stored in these components are wrapped in many layers of abstractions and we believe that adding fields will either confuse the reader or give an incorrect understanding of what is contained in these components.
#### Changes

N/A

---
### 33.
#### Criticism
If the Base plugin is always loaded, perhaps the Plugin cardinality is incorrect. Task also appears to be missing a cardinality (to the external observer it is not obvious whether a PublishedArtifact can be associated with multiple Tasks.)
#### Decision
Ignore
#### Justification for decision
The assumption that the Base plugin is always loaded is incorrect. We also scoped out PublishedArtifact from our views and thus the criticism is no longer applicable.
#### Changes

N/A

---
# General AD Feedback

### 34.
#### Criticism
A glossary would be useful. Several terms caused confusion during the presentation and were sometimes employed inconsistently : <Source Code, Data/Metadata, Gradle build, Dependency, Tasks/Actions
#### Decision
Completely address
#### Justification for decision
We recognize that some terms can be confusing especially when they are not used consistently throughout the AD
#### Changes
We will include a glossary which includes terms we believe are confusing. We will also review our AD to ensure that the meaning of terms are consistent throughout the AD. 

---
### 35.
#### Criticism
Where does dependency management fit into all this? We understand that Gradle is more of a processing service and doesn't manage lots of data (as opposed to a database system), but from a high-level, user's POV, one important piece of data that Gradle does manage are library dependencies. While these are somewhat represented in the ArtifactRepository component, it's not clear how this component interacts with the others and how dependencies are woven into the project.
#### Decision
Ignore
#### Justification for decision
We believe that detailed explanations regarding dependency management will be software implementation details rather than architecturally significant information. We will not be addressing this due to timeliness constraints of our AD.

#### Changes
N/A

---
### 36.
#### Criticism
The views do not contain any code references or supporting evidence (e.g., links to data generated by analysis tools). It would be useful if there was a tangible reference to the system, both for proof, and as a pointer for further investigation.
#### Decision
Completely address
#### Justification for decision
We recognize the lack of evidence throughout our AD.
#### Changes
We will add evidence via hyperlinks throughout our AD.

---


