diff --git a/assessment/supplementary/main.tex b/assessment/supplementary/main.tex index b482a44b..7791f82f 100644 --- a/assessment/supplementary/main.tex +++ b/assessment/supplementary/main.tex @@ -116,7 +116,7 @@ \section{Design} Your C4 diagrams need to show which AWS services are being used to deliver each part of your architecture (e.g. via the \link{Structurizr AWS theme}{https://structurizr.com/help/themes}). The C4 diagrams should go down to the code level. -Appropriate code level diagrams to use are C4 dynamic diagrams, and/or UML class diagrams and sequence diagrams. +Appropriate code level diagrams to use are C4 dynamic diagrams, UML class diagrams or UML sequence diagrams. You do not need to provide code level diagrams for the entire system, but you do need to provide code level diagrams that demonstrate how the key features of the system will be implemented. These key features are: @@ -130,99 +130,41 @@ \section{Design} \section{Evaluation} -You need to test the software system that you implement to demonstrate -how well its architecture supports delivering system functionality and its quality attributes. -This evaluation should be based on the proposal's evaluation plan, but should \textbf{\emph{not}} be limited to only what is in that plan. -You will be assessed on how well you test your system in terms of both functionality and quality attributes. -Discovering issues with the system or its architecture during testing will not adversely affect your marks for the evaluation component of the assessment. - -A section of your project report needs to summarise the test results and provide access to the full suite of tests. -You should automate as much of the testing as possible. -Any manual tests need to be documented so that they can be duplicated. -The results of all manual tests need to be recorded in a test report. -This may be a section of the project report, or it may be a separate document with a link to it from the project report. -You need to include test code and test infrastructure in your project's repository. +You need to describe how you would test the TradeOverflow system to demonstrate that it delivers its key non-functional requirements. +What infrastructure and test environment would be needed to perform adequate testing? \section{Report} The report should include the following content. \begin{description} - \item[Title] Name of your software project. - \item[Abstract] Summarise the key points of your document. - \item[Changes] Describe and justify any changes made to the project from what was outlined in the proposal. - \item[Architecture] Describe the MVP's software architecture in detail. - \item[Trade-Offs] Describe and justify the trade-offs made in designing the architecture. - \item[Critique] Describe how well the architecture supports delivering the complete system. - \item[Evaluation] Summarise testing results and justify how well the software achieves its quality attributes. - \item[Reflection] Lessons learnt and what you would do differently. + \item[Diagrams] C4 diagrams of the system's architecture. + \item[Architecture] Textual description of the software architecture. + \item[Justification] Describe how the architecture delivers the key non-functional requirements. Justify the architectural choices you made in the design. Explain why the selected AWS services are suitable to deliver the key non-functional requirements. + \item[Evaluation] Summarise how the TradeOverflow system could be tested. \end{description} You do not need to have sections for each topic above, though your report needs to contain the content summarised above. -For example, the description of the architecture could include discussion of trade-offs. -Similarly, the critique and evaluation could be combined so that both are discussed in relation to an ASR. - -When writing your report, you may assume that the reader is familiar with the project proposal. -You will need to describe any changes your team has made to the original proposal. -A rationale should be provided for each change. -Small changes only need a brief summary of the reason for the change. -Significant changes to functionality of the MVP, or changes to important quality attributes, -need a more detailed justification for the change. -You should provide a reference and link to the original proposal. - -Describe the full architecture of your MVP in enough detail +For example, the architectural description and diagrams could be interleaved with each other. + +Describe the architecture of the TradeOverflow system in enough detail to give the reader a complete understanding of the architecture's design. -Use appropriate views, diagrams and commentary to describe the software architecture. -You should describe parts of the detailed design that demonstrate how the architecture supports delivering key quality attributes. -(e.g. If interoperability was a key quality attribute, you would need to describe the parts of the detailed design that support this. -For example, how you use the adapter design pattern to communicate with external services.) - -Describe any trade-offs made during the design of the architecture. -Explain what were the competing issues% -\footnote{``\href{http://www.cs.unc.edu/~stotts/COMP723-s15/patterns/forces.html}{Forces}'' in design patterns terminology.} -and explain why you made the decisions that resulted in your submitted design. - -When describing the architecture and trade-offs, -you should summarise and/or reference ADRs that relate to important decisions that affected your architecture. - -Your critique should discuss how well the architecture is suited to delivering the full system functionality and quality attributes. -Use test results to support your claims, where this can be shown through testing. -For quality attributes that cannot be easily tested (e.g. extensibility, interoperability, ...), -you will need to provide an argument, based on your architectural design, about how the design supports or enables the attribute. -Some quality attributes (e.g. scalability) may require both test results -and argumentation to demonstrate how well the attributed is delivered. - -Summarise test plans and test results in the report. -Provide links to any test plans, scripts or code in your repository. -Where feasible, tests should be automated. -Describe how to run the tests. -Ideally, you should use \link{GitHub Actions}{https://docs.github.com/en/actions} -to run tests and potentially deploy artefacts. - -Your report should end with a reflection that summarises what you have learnt from designing and implementing this project. -It should include descriptions of what you would do differently, after the experience of implementing the project. -Describe potential benefits or improvements that may be delivered by applying the lessons you have learnt during the project. - - -\section{Repository} -Your team will be provisioned with a repository on GitHub. -All development work and documentation are to be committed to the repository. -All project artefacts are to be submitted via this repository. +Describe the parts of the detailed design that demonstrate how the architecture delivers the three key features described above. -\begin{itemize} - \item Model artefacts (e.g. Structurizr DSL or PUML files) should be stored in the \textbf{\texttt{/model}} directory. - \item ADRs are to be stored in the \textbf{\texttt{/model/adrs}} directory. - \item The report must be stored in the \textbf{\texttt{/report}} directory. - \item The link to your demonstration video must be in a file called \textbf{\texttt{demo.md}}. -\end{itemize} -Do \textbf{\emph{not}} commit large binary files to the repository. -(i.e. Do not commit Word documents or frequently changing PDF files to the repository. -Do not store your demonstration video in your repository.) -It is recommended that you use LaTeX, or possibly markdown, to write your report. -If you use LaTeX, you should use GitHub actions to produce a PDF of the report. +\section{Presentation} +You must complete a presentation as part of this supplementary assessment. +You cannot pass the assessment without completing the presentation. +The presentation will consist of a five minute summary of your architectural design. +You should use diagrams from your report to help the audience understand your architecture. -Your final submission will be what is in your repository at the due date of 16:00 (AEST) on 5 June 2023. +After your five minute summary, you will need to answer questions about your architectural design. +Questions may ask you to +\begin{itemize}[itemsep=3pt] + \item explain parts of the detail of your architecture, + \item justify choices made in your architectural design, or + \item justify the technologies or services selected to deliver the architecture. +\end{itemize} \section{Academic Integrity} @@ -231,116 +173,13 @@ \section{Academic Integrity} {https://web.library.uq.edu.au/library-services/it/learnuq-blackboard-help/academic-integrity-modules}. Submissions will be checked to ensure that the work submitted is not plagiarised. -All code that you submit must be your own work or must be appropriately cited. -If you find ideas, code fragments, or libraries from external sources (e.g. Stack Overflow), you must \link{cite and reference}{https://web.library.uq.edu.au/node/4221/2} these sources. +The architecture design must be your own work and may not contain significant copied design structures. +You may find ideas for solving common architectural problems from other sources. +You must \link{cite and reference}{https://web.library.uq.edu.au/node/4221/2} these sources, and you must clearly identify what you used from those sources. Use the \link{IEEE referencing style}{https://libraryguides.vu.edu.au/ieeereferencing/gettingstarted} for citations and references. -Citations should be included in a comment at the location where the idea is used in your code. -All references for citations must be included in a file called \texttt{refs.md}. -This file should be in the root directory of your repository. - -You are encouraged to use a generative AI tool (e.g. copilot) to help you write the source code for this project. -The expectation is that the software architecture and detailed design are your team's own work. -Create a file in the root directory of your repository called \texttt{ai.md}. -In \texttt{ai.md} indicate which files contain code produced with the assistance of an AI tool. -Estimate how much of the code was produced by the tool and how much was your own work -(e.g. \texttt{logic.py ~~~40\% generated}). - -You may use libraries to help implement your project. -The library's license must allow you to use it in the context of your project. -All libraries used in your project must be listed in a file called \texttt{libs.md}. -This file must be in the root directory of your repository. - -Uncited, unreferenced or unacknowledged material will be treated as not being your own work. -Significant amounts of cited material from other sources will be considered to be of no academic merit. -Having an AI tool produce significant amounts of source code is acceptable, -if the design is your own and you have verified that the code is correct. - - -\section{Demonstration} -Your team needs to demonstrate your project's functionality and how well it achieves its goals. -This should include demonstrating how quality attributes are achieved, -or briefly summarising how the architecture facilitates delivering a quality attribute. - -Your project demonstration will be a video. -Provide a link to the video in a file called \textbf{\texttt{demo.md}}, stored in the root directory of your repository. -Do \textbf{\textit{not}} store the video in your GitHub repository. -The link may be to the video on a platform like YouTube, or a file sharing site from where the video may be downloaded. -If you upload the video to a platform like YouTube, you may make it private. -If it is a private video, you must share it with \texttt{richard.thomas@uq.edu.au}, \texttt{b.webb@uq.edu.au}, -\texttt{evan.hughes@uq.edu.au}, \texttt{m.holloway@uq.\textbf{net}.au}, and all of your team members. -The video must remain available until at least 31 July 2023. -Viewers must be able to easily see what is being demonstrated and read any text or images. -Audio must be clear and comprehensible. -The video timeline should be as follows. - -\begin{description} - \item[3 min] Introduction to the project. - \item[3 min] Demonstration of the functional requirements. - \item[3 min] Demonstration of the non-functional requirements. - \item[3 min] Overview of the software architecture. - \item[3 min] Summary of your reflection on lessons learnt from implementing the software. -\end{description} - -\noindent -The total duration of your video should be \textbf{\emph{less}} than 15 minutes. - -\paragraph{Introduction} Briefly introduce the project context and summarise the delivered functional and non-functional requirements. -Mention any differences between what was originally proposed, what was renegotiated, and what was delivered. -Briefly explain why changes in scope were made. -The tutor who may have approved a change in scope may not be the tutor marking your demonstration. -If you did not deliver everything in the revised scope of the project, the marker needs to know why that occurred. - -\paragraph{Functional Requirements} Demonstrate the key features of the software. -You do not have time to demonstrate every feature of the software. -Plan your time wisely to highlight the completeness and quality of your delivered system. - -\paragraph{Non-Functional Requirements} Show how well the software delivers its important quality attributes. -This may take some thought and planning to demonstrate within a short time frame. -Delivery of some non-functional requirements can be shown by test results. -Delivery of other non-functional requirements may be shown through a combination of tests, metrics, and commentary. - -For example, you cannot show ten minutes of k6 testing to demonstrate scalability. -You could provide screenshots of different stages of the testing, or an edited video of parts of the testing. -You would provide commentary summarising how the testing was done and explaining how well the system scaled under different loads. - -For security, you could show results of simple fuzz testing of APIs. -You could then show examples of parts of your design, explaining how it demonstrates following key security design principles. - -For extensibility or interoperability, you could calculate one or more complexity metrics for parts of the design. -You could then use the data from these metrics to support an argument as to why the design was extensible or had a simple interface. -For example, if many interfaces could be shown to have high cohesion and there was low coupling between different modules -or services in the design, you could argue how this shows that the design is likely to be extensible. -You could measure documentation for interfaces or APIs, -and use that to argue that mechanisms used to extend the design, or that the APIs, were comprehensible. - -These are examples to help you to start thinking about demonstrating how your design delivers non-functional requirements. -They are not a definitive list of the only or best approaches. -For the demonstration, focus on the most important non-functional requirements for your project. -You should discuss your ideas with a tutor if you are unsure of the effectiveness of an approach. - -\paragraph{Software Architecture} Provide an overview the system's architecture. -Briefly explain how well it supports delivery of the MVP's, and the full system's, functional and non-functional requirements. - -\paragraph{Reflection} Summarise the lessons you learnt from implementing the software. -What would you do differently and why? -Explain how you would apply those lessons to design a different architecture or take a different approach to implementing the project. -Or, explain how the lessons learnt demonstrate that you made good choices at each stage of development. - -\paragraph{Presentation} There are no constraints on who in your team presents in the video. -One person could present all parts of the video, or you could have different people presenting each part. -Assume that the viewer has read the project proposal but may not yet have read the project report. - -%You may use this \link{booking page}{https://calendly.com/richard-thomas-uq/csse6400-demo} -%to schedule a time to demonstrate your project between June 10 and 17. -%The demonstration is to take a \textbf{maximum} of 20 minutes. -%Your system must be deployed and set up so you can start your demonstration \textbf{immediately}. -%You should not take demonstration time to do any deployment or initialisation. -% -%When you book the demonstration time, you will be sent a confirmation email with a Zoom link for the demonstration. -%Only \textbf{one person} from your team should make a demonstration booking. -%Ensure you discuss with your other team members to find suitable times that are available for booking, -%and for which at least all of your key team members are available. +Uncited, unreferenced, or unacknowledged material will be treated as not being your own work. +Significant amounts of cited material from other sources will be considered to be of no academic merit. \section{Grading Criteria} @@ -356,8 +195,4 @@ \section{Grading Criteria} \input{criteria} - -\bibliographystyle{ieeetr} -\bibliography{ours} - \end{document} \ No newline at end of file