| Title | Author |
|---|---|
Project Requirements |
Neil Ernst |
The course project is a semester long effort to apply the ideas behind code reading and communication to a realistic project.
Your team gets to choose the project you will work on (subject to some restrictions). In general the project must be active (daily commits), moderately large (>100 stars on GH, but not intractably complex), and open-source. Since other teams have done this type of course, you cannot select from the banned project list. This is to avoid annoying hard-working and under-compensated OSS maintainers.
See the syllabus for all due dates.
- M0. team formation and Github (0%, -10 if not done)
- M1. identify project stakeholders and business goals (5%). Report on project ethics and privacy. (5%)
- M2. identify architecturally significant requirements and utility tree (10%)
- M3. module view (20%)
- M4. C&C view (20%)
- M5. assess project code quality and technical debt (15%)
- M6. present report in class, deliver final chapter proof-edited and well organized (5%)
- M7: using your knowledge of the project, submit a pull request that improves the project. (20%)
- Instructor assigned - see Slack
- If you are having trouble with your team (lazy group members, poor communication, technical trouble, etc.) come see me or Omar as early as possible. We cannot help you if you don't let us know. Telling me in April that the team was not effective will not be an excuse.
- A regular meeting schedule is highly recommended to keep everyone on track. You might want to follow a Scrum style standup: each team member says:
- What did you do since last meeting?
- What will you do before the next meeting?
- Are there any impediments in your way?
- You can organize how you wish, but everyone must contribute, and one person should be in charge of overall planning.
All students are expected to participate equally in discussions, design and development. The instructor will make marking adjustments for individual students where this participation has not occurred; this may result in a failing grade for the project. At the mid-point and conclusion of the project you will be asked to evaluate your colleagues on the team. Your peer review score and participation on Github/Slack will strongly influence what percentage of the project mark you get.
The final team deliverable is a book chapter that we will publish on Gitbook. Gitbook accepts both Markdown and ASCIIdoc; both of these are described on the Gitbook help pages. You will write the submissions in a Github team repository with standard text editors. Markdown and ASCIIdoc editors are also plentiful. I like Byword and Marked.
Your final presentation will be an architecture presentation, of the system you chose, to the entire class. Keynote/Powerpoint etc are suitable here.
Note that since we are documenting and communicating, good technical writing practices (spelling, grammar, organization, clarity) are always required and will be subject to lost marks if not followed. You can always reach out to the Center for Academic Communication if you need extra assistance.
See the syllabus.
- Create a repository using the Github Classroom link
- send your Github IDs to Omar
- update the Readme with your team's name, and 3 projects of interest.
Simple. Do the above.
This deliverable will serve as an introduction to the project you have chosen to focus on. You will read project documents and related material (e.g., StackOverflow) to get a sense for who the stakeholders are, and what the project wants to accomplish. Use your judgment, plus available sources, to create a plausible set of stakeholders and business goals. NB: Since we don't have direct access to the stakeholders, our business goals are necessarily a guess. But it should be an informed guess.
After that, you will examine project policies around privacy, security and ethics, and write a 2 page summary of this. Use the ACM Code of Ethics, assess how the system you are studying currently complies with this Code, and identify places where future ethical conflicts may arise.
See the syllabus.
- Identify stakeholders for the system you chose. Complete a stakeholder profile table, and explain why those people/job titles are stakeholders for that role.
- Create a list of at least 5 business goals (see chap 16) for this system. We will use those in M2 as well.
- 2 page report on privacy and ethics concerns for this project:
- Title
- Introduction
- Potential Privacy and Security COncerns
- Ethical Dilemmas
- Summary
- Sources (issue tracker discussion, wiki/web pages, commit comments, media reports).
- completeness and relevance of stakeholders.
- properly thought out business goals, based on empirical data (project docs, tech pubs, etc.)
- proper formatting and references supporting concl usions
- evidence of critical assessment of possible ethical dilemmas
See the syllabus.
- The list of ASRs
- A fully worked out utility tree, with at least 7 prioritized quality attribute scenarios, 3 (of the 7) in template form.
- Relevance of the ASRs to the project.
- Appropriateness of scenarios.
- Quality of scenarios.
A module view (see Chapter 18 in the text) describes implementation units of the system. In this milestone, you are to create a software architecture view that shows the module structure of your system. Your deliverable will be a Markdown document that follows the template described in Section 18.6 of the text.
The purpose of this document is to support analysis of some of the key quality attributes you identified in Milestone 2. The reader will be someone who is not very familiar with the code or project, so be sure to explain it to an interested outsider (e.g. someone who just joined the dev team).
Your deliverable should be laid out and contain material very similar to this one from the SEI.
- Identify QAS that pertain to implementation units and responsibilities. Some obvious categories include modifiability, portability, use of 3rd party frameworks.
- Choose a view type that supports analysis of these QAS. Some of the view types we discussed were Layers, Uses, Data Models (see lecture notes). Others include Decomposition and Generalization (is-a).
- Create a primary presentation of that view (the main diagram). Remember the key. Please use a tool of some kind to create the diagram. I suggest Visio, Powerpoint, Omnigraffle, or some of the open source alternatives. As you do this create the element catalog describing each element/relation.
- Outline the context diagram for that view, using the same 'language' (i.e., for a 'uses' diagram, the context shows the external elements 'used').
- Document the view's key behavioral questions in a behavior diagram. For example, you might want to show the way in which login code interacts with a 3rd party authentication framework.
- Give 2 important interfaces for this view. We have not discussed interface notations yet, so this element will be for bonus marks. You can read the SEI whitepaper for the details.
- Typically one includes a variability guide, but we will skip this section. A variability guide describes how and why the view might change.
- Finally, provide at least 500 words of rationale explaining why you think the designers organized the system's modules this way. You should explain this with specific reference to the quality attribute scenarios in M2.
See the syllabus.
A fully worked module view according to the SEI view templates. Includes interface and behavior documentation. Deliver this as a Markdown document in your repository.
- all required sections are present and well-organized. Include a table of contents (see this tool).
- view's primary presentation (diagram) is thorough and understandable. This means key elements are labeled, relations are typed, color is used appropriately. Use of UML or other diagram notations is not mandatory.
- view and element catalog answers key analysis questions implied by QAS (M2).
- behavior diagram is appropriate and clearly answers important questions from the QAS.
- rationale is well-reasoned and any obvious assumptions are documented.
- Architecture Reconstruction of J2EE Applications: Generating Views from the Module Viewtype Liam O' Brien Vorachat Tamarree. 2003. Describes a case study of generating module views from an existing system
- A7e Case Study. From the 2nd edition, this case study shows how a module decomposition and uses views can answer QAS questions.
- SEI example. A hypertext example of a fully worked out module view (and other parts of the documentation package).
Like the module view in M3, choose a C&C view to answer important questions from your QAS in M2. Deliverables will be identical to M3, except your primary presentation will be a C&C view (Pipe-Filter, Client-Server, Service, and so on.) You will also include interface documentation and a short variability guide.
Note in particular the aspects of M3 that you lost marks on. In general, this was typically having a primary presentation that was much too complex; failing to correctly link elements in the Github source code to the diagram; and failing to show how the view can answer key questions in your QAS. Remember, your task is to simplify the details in the codebase so I can understand it.
Focus on a single quality attribute scenario from M2, and make sure your diagram explains that.
See the syllabus.
A fully worked C&C view according to the SEI view templates. Includes interface and behavior documentation.
Identical to M3. No bonus marks. Ultimately I need to be convinced your team has a good understanding of important run-time functionality of your system. A good way to do this is to get the system running and trace a simple end-to-end run of core parts of the code. For example, in Toyplot I might walk through a simple tutorial and explain how each component in Toyplot gets called in turn to get a plot displayed. Running tests is another way to simulate this.
Assess your project's architecture and code quality. using automated tools like Pylint, FindBugs, CppLint, Sonarqube, CodeScene. The last two are more tricky to configure so start early. Then write a report documenting what you have found, and any possible technical debt the project might be facing.
By now you ought to have a good grasp of the internal structure of your projects, and some idea of what exactly its architecture is. Recall from class lectures that technical debt reflects the short-term decisions with potential high longer term costs.
- Run one of the tools like SonarQube, CodeSonar, CodeClimate, Quality Inspector, etc. Feel free to find a different one (but let me know).
- Search the project's issue tracker looking for shortcuts; good keywords include "technical debt" and "tradeoff". You can likely think of others.
- Search the project's code for instances of "Fixme", "Hack", etc. Keep in mind, however, that we are really looking for design flaws, not just bad coding practice.
- Have one or two team members report on the code quality tool report. Read the report, and summarize what you find. This should be prepared as though you were giving a 10 min summary to an executive.
- Other team mates should combine the output of steps 2/3 and their knowledge of the design from previous milestones, in order to report on possible design problems due to technical debt. Make sure your reporting uses evidence from the code/issues/other docs to make the case. Nearly every project maintainer would love more time to just refactor the codebase, so figure out where they would spend that time.
See the syllabus.
- Code quality report. Analyze potential technical debt in the project. Report at least 2 potential shortcuts or design tradeoffs that might have long-term consequences. Use tools like SonarQube to augment the report with specific metrics and insights.
- Architecture quality assessment. Using one of your QAS, provide an assessment of where the architecture meets and doesn't meet the QAS response measures. In other words, where might improvmeents be necessary?
- insightfulness of your analysis
- plausibility of the design debt you identified
In class presentation of 10 minutes; final report polished and cleaned up (e.g. add introduction, conclusions, references). Not everyone needs to present, but everyone needs to work on the milestone.
Odd, Tuesday, Even, Wednesday.
- Introduction (1 minute)
- Business goals, elevator pitch to set context and why it's cool
- QAS (1-2 minutes)
- List the most important QAS here
- Technical content (3-4 minutes)
- Brief technical overview: explain what language it is written in, key drivers and constraints
- One of:
- Implementation/ module view (M3)
- C&C View (M4)
- Technical Debt and Quality (1 minutes)
- give one place where the design seems to be lacking, based on metrics and your analysis.
- Reflection (1-2 minutes)
- Challenges
- What worked well
- Questions
- Audience: technical people
- VGA adaptor
- Projector not widescreen
See the syllabus.
Use the GitBook toolchain to ensure your chapter compiles to something readable on the site.
Presentation must be attended by all group members, all of whom may be asked questions about the project.
- Presentation organization
- Presentation competently run
- Presentation on time.
- Report compiles to PDF/Gitbook
- Report has all necessary sections.
- Report has fixed comments from previous submissions.
See the syllabus.
Link to a pull request for your case study, showing an improvement. The PR does not need to be accepted, but you get a 5% project bonus if it is.
Silly or trivial pull requests will lose marks. It does not have to be complex, but does have to demonstrate you understand the project and are not just annoying the maintainers.