This template was made as a guide to help ensure you cover assessment criteria in your third mileston write up. It is specific to the Milestone 3: Flask Backend Development project.
There still is not an official readme example for this Project Provided by CI.
Sections marked as 🚨Required and 🚀 merit & beyond
Please note that project assessment criteria changes more often than these guides are updated so double-check the submission criteria before assuming the 🚨Required is all you have to do to pass.
Here’s a cheatsheet on how to navigate into functions and to the next line using pdb.
This video shows you how to set a trace and then use the print() to evaluate variables
GitpodPdbDebugging.mp4
Here’s a great video on how to add videos to your readme! no need to convert to gifs!!
https://www.youtube.com/watch?v=G3Cytlicv8Y
- record a video via slack
- download it
- in github, edit your readme via the pencil icon
- type a place holder word and highlight it
- drag and drop mp4 file over that text
- scroll down to the commit area
- update the default commit message
- click the green button
git pullchanges to your gitpod workspace
You can do the steps 3-9 for the image/screenshot uploads too!
Markdown's not all that easy so sometimes you may want to use some tools to make tables.
- Markdown Cheatsheet
- markdown table generator - used to help with documentation table formatting
- markdown table of contents generator - used to create table of contents (be weary these tools have some bugs if you have dashes or trailing spaces in your headers)
- readme.so - if you don't want to learn markdown, this tool might help you
🚨Required
replace the PROJECT NAME header with your project's name
- One or two paragraphs providing an overview of your project.
- Write this as a sales pitch or commercial to entice users to interact with your site or how you want investors to invest in or purchase your website.
- Include a picture of site that shows it in responsive states and links to deployed code: https://ui.dev/amiresponsive
🚨Required
- Include a link to deployed project (typically a Heroku Page)
🚨Required
- Include a Link to the GitHub repository
🚨Required
DEVELOPER_NAME (take credit for the work you do!)
🚀 merit & beyond
- OVERVIEW
- PROJECT_NAME
- Table of Contents
- HOW TO USE
- UX
- Information Architecture
- Features
- Defensive Programming
- Testing
- Technologies Used
- Deployment
- Credits
Generate after readme is complete by copying and pasting your readme from this point & below into this tool:
- mardown table of contents generator NOTE: It does have some bugs if you have dashes or trailing spaces in your headers, so make sure all these WORK!
🚀 merit & beyond
This project requires DATA INTERACTION, if you set up user authentication, you should include example accounts to use in your heroku deployment so the assessors can use your site. Ideally you'd record yourself using the site in slack. Download it to your computer then drag and drop that into your README.md while editting it in github.
🚨Required
🚨Required Talk about how you landed on your final idea and how you see this idea being useful to both users and site owners.
🚨Required Talk about long term plans of ths site and what lead you to the MVP (Minimal Viable Product) you delivered.
🚨Required Use this section to provide insight into your UX process, focusing on who this website is for, what it is that they want to achieve and how your project is the best way to help them achieve these things.
🚀 merit & beyond
Write goals form the perspective of each user group of your website. Common types of users are:
- new users
- existing users
- admins
- logged in user
- unauthenticated user
- followers
🚀 merit & beyond
List out the goals as a developer you hope to achieve by making this website.
🚀 merit & beyond
List out any goals a website owner would have for this website. You may not develop them, but investors would want to know how they could make money.
🚀 merit & beyond
In particular, as part of this section we recommend that you provide a list of User Stories, with the following general structure:
As a user type, I want to perform an action, so that I can achieve a goal.
🚀 merit & beyond
To scope the project for a MVP (minimally viable product) a feasibility analysis was done.
The features in the table below have been taken from the user stories above. Generic features found in most websites will also be implemented such as nav-bar, footer, obvious website purpose etc.
| Opportunity/Feature | Feasibility/Viability (score out of 5) | PurposeLevel of Importance (score out of 5) | In Or Out |
|---|---|---|---|
You should discuss the outcome of what you will be dropping based on the outcome. Making a scatter plot of the scores and coloring the dot
🚀 merit & beyond
our site is most likely geared to a certain audience with a certain interest, that is looking for what your site offers. The type of users, age, gender, interests, and the topic of the site drives many UX decisions so write out what whom you expect to use your site.
🚀 merit & beyond
Now that you have let the assessors know about the target audience and users, you can go into the design choices
🚀 merit & beyond
- Discuss your color pallet choices and how it ties into users' emotions or target audience.
- include a screenshot of your pallet using a tool like coolors.co
🚀 merit & beyond
- discuss font size, font types for headers vs buttons vs general text and how it ties into users' emotions or target audience.
- include screenshots of fonts used and links to the appropriate website ex) https://fonts.google.com/specimen/Raleway
🚀 merit & beyond
Explain why you used certain icons and images on your site
🚀 merit & beyond
- list out the type of elements you want to use on your site, this will help you when choosing a framework and goes hand in hand when doing the wireframes. If you did something out of the ordinary, or think something was particularly clever, add a sentence and a screenshot or reference the file the code or css is in.
- desktop navigation
- mobile navigation
- footer
- containers/cards
- buttons
- text input
- textarea inputs
- dropdowns
- modals/layers
- check boxes
- switches
- accordions/drawers
- pagination
- date pickers
- maps
- images
- tooltips
- icons
- tabbed content
- file pickers
- video players
- audio players
🚀 merit & beyond
- discuss any special animations or transitions you've programmed
- special hover state effects
🚨Required
- If you use bootstrap, tailwind, bulma, materialize or some other JS/CSS framework, call it out here and why you made that choice. (Typically I look at the design elements I want and make sure the framework supports them)
🚨Required
- call out any overrides you did for bootstrap styles or the framework you used, even if they are fonts and colors, perhaps lead assessors to the file of interest in your repo
🚨Required
- call attention to any custom javascript you created to help your User Experience you can organize this by functions or files
🚨Required
This section where you would share links to any wireframes, mockups, diagrams etc. that you created as part of the design process.
- you need mobile & desktop views
- Capture Your Custom model's
- CREATE/ADD
- READ (LIST/DETAIL)
- UPDATE/EDIT
- DELETE
- & triggers for such things
- call out differences for authentication levels:
- not logged in
- general user logged in
- super user logged in
- HOW is the NAVIGATION different for admin users vs Logged-in users & unauthenticated users
🚀 merit & beyond
- tablet views
- Custom 404
- Profile Page
- Login
- Register
- Forgot Password
You can hand draw these, but CI posts a yearly license in the general channel for Balsamiq which is pretty easy to use. Here is the 2023 announcement
🚨Required
As part of the requirements for this project you need to have at least 1 original data model. It's this section that discusses your data and how each piece relates to another.
- draw.io - is a free program that can be used to create Entity Relationship diagrams and CRUD flow diagrams.
🚨Required
Use some type of spreadsheet or even draw out one by hand, but you should show how your data models are related to each other or what those tables are even if they are entirely separate from each other.
🚨Required
Write out which database(s) you used and why sometimes you use a different one for local vs production.
🚨Required
Show the accessors you know your data. If you end up using some data models from an example project, call that out and don't be as detailed about writing those up unless you added to them.
Each data model that you created yourself should have its Fields, Field Type and any validation documented. You should also cross-reference any code in your repository that relate to CREATE, READ, UPDATE, DELETE operations for these models.
You can try to use markdown, or just take a screenshot from a Google spreadsheet.
Below is an example of a write-up for an Activities Data Model
Activities Model Activities is a table to hold a unique icon image and name values that users have associated with events and places. It helps with sorting events and prevents the need from carrying around two data objects in the larger Events and Places data structures. The purpose of an Activities object is to provide an imagery association to a category.
DB Key Data Type Purpose Form Validation DB processing _id ObjectId unique identifier None n/a name String Name of Activity Required
Min 1 char
Max 50 charstrim
to lowericon String system path to image file Required Activity entries are used by events, places and filtering.
- Create - An activity is potentially created when a user successfully creates a place, creates an event, updates an event, or updates a place.
- Read - The Activities table is read when a user is adding an event, updating an event, adding a place or updating a place, to determine if a new value should be created or not. The activities table is queried for using the name and icon pair, if it is found, the ObjectId is passed to the event and places. If no match is found, a new Activity is created and that ObjectID is passed to the place or event.
- Update
- Delete > > This table has no deletion or updates associated with it. It's strictly create and read. Eventually, maintenance scripts should be written to delete unused/deprecated entries.
The reading/writing of the activities table is housed in the what2do2day/activities/views.py file.
🚀 merit & beyond
It might be overkill, but you could document the flow of how your CRUD operation logic works if its full of complex logic. Using a flow diagram or process diagram might make it easier for accessors to understand the inner workings of your program.
I used draw.io and hooked it up to my google drive to create the screenshot below
🚨Required
In this section, you should go over the different features of your project, and describe each in a sentence or so along with a screenshot.
For some/all of your features, you may choose to reference the specific project files that implement them, although this is entirely optional.
It's easiest to break this section down into by pages and common page components such as home page, products page, product detail page, product sort buttons, navigation, and footer. Call out differences between viewports as needed.
Don't forget your 404 and 500 error pages.
Don't forget the 3 phases of navigation:
- unauthenticated
- general authenticated user
- superuser authenticated
And don't forget Defensive programming bits
- validation of form inputs
- not allowing users to create, read, update and delete information they shouldn't
For some/all of your features, you may choose to reference the specific project files that implement them, although this is entirely optional.
🚀 merit & beyond
Use this section to discuss plans for additional features to be implemented in the future:
If you end up not developing some features you hoped to implement, you can include those in this section.
🚨Required
Sites with admin rules and roles opens a site up to hacking especially if your users are savvy and notice url parameters correlate to database object manipulation. If you did anything above the basics to defend your application against hacking write them out here. You want to make the accessor's job easy by stating what you did to keep the data safe.
🚨Required
In this section, you need to convince the assessor that you have conducted enough testing to legitimately believe that the site works well. Essentially, in this part you will want to go over all of your user stories from the UX section and ensure that they all work as intended, with the project providing an easy and straightforward way for the users to achieve their goals.
If this section grows too long, you may want to split it off into a separate file and link to it from here.
🚨Required
In this section you should write up any websites you used to validate your code and include screenshots.
Validation issues are an automatic failure You should run these about 3 times:
- when you first deploy your site
- just when you think you are done testing
- right before you submit because 😼, ⚽, 🐶 & 👼 can eliminate a closing tag or curly bracket without you noticing.
🚨Required
The Jigsaw validator was used to validate CSS.
If you only have one CSS file, you can just run the validator through one deployed page URL, if you have custom CSS for different pages, make sure you hit those different URLS, or do direct input on each file.
Include a screenshot for each CSS file which includes the Green no ERRORS bar, two check marks:
styles.css
🚨Required
The W3 HTML Validator was used to validate HTML by coping the page source as a direct input.
For each view/route you wrote, you should validate the HTML and have a screenshot NOTE: You may need to right-click to view the source of each page and paste that into the validator if you need to go through authentication to get to the page. The screenshot should have from blue to blue line. The Go Full Page chrome extension in is good if you have a long bit of output.
🚨Required
The Jshint validator was used to validate each JS file.
for each .js file, copy the code and paste it into this site, and have a test case for it linked to from here. You can have warnings, but no errors. if using ES6, add this before pasting in your file:
/*jshint esversion: 6 */, similarly you can update it to 7 if you see warnings about ES7 syntax/*jshint esversion: 7 */
🚨Required
CI's pep8 tool was used to validate each .py file created.
for each .py file you created, copy the source code and paste it into this site, and have a test case for it linked to from here. include a screenshot of results in the test case showing NO ERRORS. (you should do this for all .py files in your repo
run.py
Ideally you would have no errors remaining outside of line too long which you can fix by
adding
# noqa
There is a space before the # and after it to skip the quality assurance for that line.
Note any errors or warnings you are ignoring and why.
🤷 Required if you made some files The JSONLINT validatior was used to validate JSON files.
for each .json file, you should copy the code and paste it into this site, and have a test case for it linked to from here.
🚨Required
Accessibility testing is aimed to make sure that those with visual or physical disabilities can still browse your website. Some users have had strokes or accidents that make it difficult to use a mouse, so they use keyboard keys to tab through sites. Others use screen readers that rely on HTML tags to help the user navigate quickly through the site to find information they want, others have color blindness or contrast issues. It's the law to provide services Here's a site where you can learn more about accessibility and the internet.
🚨Required
Accessibility audits run through the HTML and determine if the parts of the WCAG (web content accessibility guidelines ) that are implemented through HTML tags and attributes are present. They can do some checking for low vision/contrast stuff too.
You should run your deployed website pages through at least on auditing tool. lighthouse's audit to check performance, accessibility, best practices and SEO scores. You should aim to get 85 or higher score on accessibility.
You should fix issues associated with:
- contrast
- aria labels
- alt text
- large images
- skewed images
Lighthouse https://web.dev/measure/ If you have lower scores, read the report and follow the links to address the flagged issues. You can run this tool from Chrome Dev Tools too against your local machine, but chrome extensions can sometimes give you missing alt text on things like the grammarly plug in tracking pixel.
You want a score in the green for accessibility and should look at ways to get it to 100.
WAVE chrome extension Wave is developed by webaim.org and does a bit better at contrast issues and uses 2.1 guidelines
Contrast Checkers
🚀 merit & beyond
Another way to accessibility test your site is to try to click on the browser URL and see what happens if you use the tab, arrow and enter keys. Does it work well or does the user get stuck? Check this in a couple browsers as the focus & active outlines are typically styled by the browser
The expected results for various keyboard entries and field types can be found here
You can take a video of this testing if you want and convert it to a gif and paste that into your readme. Record something to yourself in a Slack direct message, then download it. Then you can use https://cloudconvert.com/mp4-to-gif to convert the mp4 to a gif and just paste it into the readme via GiHu, and it'll resolve itself.
🚀 merit & beyond
If you are really ambitious, you can use the VoxReader extension in chrome to see what your site sounds like on a screen reader. It really drives home the need for good aria-labels & semantic HTML.
🚀 merit & beyond
SEO is greatly impacted by your core web vitals. The readout from https://web.dev/measure/ which is essentially a lighthouse audit gives your site scores in 4 categories. Ideally you want your site to be in the green for all 4 scores. web.dev has dedicated servers to test deployed sites without extensions that skew the results, so it's best to get results from this site. You should talk about the results for each section pay attention to
Create a table that lists out what devices, browsers, and operating system you tested your application on and a brief description of why you chose the mixture you did. The point is to prove that you looked at the site across various browsers, operating systems, and viewport breakpoints.
| TOOL / Device | BROWSER | OS | SCREEN WIDTH |
|---|---|---|---|
| real phone: motog6 | chrome | android | XS 360 x 640 |
| browser stack: iPhone5s | safari | iOs | XS 320 x 568 |
| dev tools emulator: pixel 2 | firefox | android | SM 411 x 731 |
| browserstack: iPhone 10x | Chrome | iOs | SM 375 x 812 |
| browserstack: nexus 7 - vert | Chrome | android | M 600 x 960 |
| real tablet: ipad mini - vert | safari | iOs | M 768 x 1024 |
| browserstack: nexus 7 - horiz | firefox | android | LG 960 x 600 |
| chrome emulator: ipad - horiz | safari | iOs | LG 1024 x 768 |
| browserstack | Chrome | windows | XL 1920 x 946 |
| real computer: mac book pro | safari 12.1 | Mohave | XL 1400 x 766 |
| browserstack | IE Edge 88 | windows 10 | XL 1920 x 964 |
🚀 merit & beyond
Whenever it is feasible, automate your tests, and if you've done so, provide a brief explanation of your approach, link to the test file(s) and explain how to run them.
If you did not run automating testing. State why you chose not to.
🚨Required
You can track your test in various ways.
But for any scenarios that have not been automated, test the user stories manually and provide as much detail as is relevant.
- Markdown
A particularly useful form for describing your testing process is via scenarios, such as:
Register Page Go to the Register page: http://.herokuapp.com/register
- Try to submit the empty form and verify that an error message about the required fields appears
- Try to submit the form with an invalid username format and verify that a relevant error message appears
- Try to submit the form with an invalid password format and verify that a relevant error message appears
- Try to submit the form with an existing username, should re-render page with relevant error message/warning
- Try to submit the form with all inputs valid and verify that a success message appears and user is on profile page
- Be logged in and go to register page url http://.herokuapp.com/register, should have error saying you are already registered and be on profile page
- Spreadsheet
Here is a Manual Testing Template that you can use as a starting point to keep track of your testing efforts. Make a copy of it in your own account and update as needed to reflect the browsers you are testing and features.
- GitHub Issues, Milestones & Boards
You can also use agile tools in github to help track your testing and defects. Here's a document that I put together about that process
It's ok to spot check specific functionality across devices and browsers but each page should be viewed as a whole for each device/browser combo at least once.
A quick way to check if items are exceeding the screen width of a project is to run this javascript in the console for various screen emulations:
var docWidth = document.documentElement.offsetWidth;
[].forEach.call(document.querySelectorAll('*'),function(el){if(el.offsetWidth > docWidth){console.log(el);}});
🚨Required
You should mention any bugs or problems you discovered during your testing, even if you haven't addressed them yet.
Here is a Defect Tracking Template you use as a starting point to track defects. Make a copy of the sheet to your own account and update the Features sheet to match your project.
Again, you could use github issues to track you defects. Or write them up with markdown.
🚀 merit & beyond
Some defects are more pesky than others. Highlight 3-5 of the bugs that drove you the most nuts and how you finally ended up resolving them.
🚨Required
It's ok to not resolve all the defects you found as long as:
- it does not impact a user from completing a vital function on the website
- it only affects a very small subset of users
- is an extreme edge case that very few users would try
- there is an open issue against a framework, browser or technology used
If you know of something that isn't quite right, create an issue and link to it here and explain why you chose not to resolve it.
Sometimes it's as simple, word wrapping issue that makes the site look odd at a certain screensize that you just didn't have time to fix due to the impending deadline it's best to mention it but note why you allowed it to go live: "Yes it looks odd, but it doesn't impact core functionality of the site." than to let the accessors think you didn't notice it.
🚀 merit & beyond
In this section, you should mention the languages, frameworks, libraries, databases and any other tools that you have used to construct this project. For each, provide its name, a link to its official site and a short sentence of why it was used.
-
If you included a js file that isn't your own, add it here.
-
If you included a css file that isn't your own, add it here.
-
Common 3rd party technologies to list:
- wirefames
- favicons
- color palette images
- fonts
- CSS Frameworks
- markdown tables
- markdown table of contents
Please note, if this gets more than 5 items, you may want to break it down into logical subsections
- CSS3 - used to style DOM appearance.
- HTML5 - used to define DOM elements.
- JQuery - used to initialize handlers for user interactive elements such as Bootstrap framework pieces like: check boxes, date pickers, menu toggles.
- JavaScript - used to help handle challenge member entry.
- Python the project back-end functions are written using Python. Django and Python is used to build route functions.
- Flask - python based templating language
- mongodb- a fully-managed cloud database used to store manage and query data sets
- Markdown Documentation within the readme was generated using markdown
🚀 merit & beyond
List out the tools you used with a link and a short description (this helps others figure out where to get the bonus points & reminds you what you used for your next project
- Balsamiq
- Coolors.co
- fontawesome
- gitpod
- github
- google fonts
- font awesome
- amiresponsive
- table of contents creator
- markdown table generator
🚀 merit & beyond
In this section you should reference any 3rd party tools you used to make your project or readme. Wireframes, faviocon, github, color palette generators, heroku and any testing emulators are things that belong in this section. Back To Table of Contents
🚀 merit & beyond
List out the API's you used for this project.
🚨Required
🚀 merit & beyond
If the user is required to have certain keys and credentials you should include this section with directions on how to get the necessary information. ex)
- Gmail Account: In order to have verification and forgot password emails sent to registered users you need a google account.
- create a gmail accoount
- downgrade to less secure after you are signed into the gmail account, downgrade to less secure
- Couldinary URL
-
go to the dashboard and copy your API environmental variable
🚀 merit & beyond To keep the main reposotory for this project clean, please fork the repostiory into your own account. GitHub has forking directions but here's what you might do:
- login to your own gitHub account
- navigate to [my repository](URL OF YOUR LIVE REPOSITORY)
- In the top right corner of the page, click fork
- set yourself as the owner
- change the name of the repo if you want
- add a description if you want
- choose what to copy, typicall the main branch only
- click the snazy green button
- To get files to your local environment, you need to clone it: click the code button
- Copy the url as needed (here's gitHub instructions)[https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository}
🚨Required
This section should describe the process someone would have to go through to get the local working in GitPod, or your preferred IDE. Start from installing the chrome extension then clicking the green gitpod button in THEIR FORKED repository, the enumerate the steps to walk them through the process as if they were brand new to this proccess. Include screenshots where applicable.
Key points to cover
- Install required python packages:
pip3 install -r requirements.txt - Create env.py
- What to put in the env.py, don’t disclose real values
- EMAIL_HOST_PASSWORD=<YOUR_VALUE>
- DEFAULT_FROM_EMAIL=<YOUR_VALUE>
- EMAIL_USERNAME=<YOUR_VALUE>
- SECRET_KEY=<YOUR_VALUE>
- CLOUDINARY_URL=<YOUR_VALUE>
- DEV=True
- Apply Database Migrations so the database starts up
python3 manage.py migrate - Create a super user so you can add and inspect things via django admin
python3 manage.py createsuperuser - Preload data: Sometimes you might want to include steps to create data in the admin or preload a data dump coderwall blog has examples on how to dump data and load it which saves a bunch of time when deploying the application from a local database to a hosted database but you don’t have to do this step
- Start the server
python3 run.py
Write out the steps you take starting from cloning the repository in github or clicking a gitpod button to run your code locally. Test it out and make sure it works. This can be running from your IDE of choice like VSCode or PyCharm or GitPod.
You may want to re-watch the videos when writing up this section.
🚨Required
This section should describe the process you went through to deploy the project to a server where anyone can access the url without your machine running. This is typically Heroku. Include screenshots if you think they would make the process easier. Start with getting an heroku account and then setting up databases and other packages.
If you have project settings required for Heroku, provide a table of the keys and values. Do not share your personal keys but either cut them out of the screenshot or say <YOUR_VALUE> and include links on how the user would obtain such values.
Key points to cover
- creating new app
- setting app name
- setting region
- entering dreaded billing info
- subscribing to a plan
- setting up db
- adding environmental values- have a list or table so user has less chance of typos
- EMAIL_HOST_PASSWORD
- DEFAULT_FROM_EMAIL
- EMAIL_USERNAME
- SECRET_KEY
- CLOUDINARY_URL
- COLLECT_STATIC
- adding build packages
- deploy
- gitHub connection
- auto vs manual deploy
- monitor logs
🚨Required
To avoid plagiarism amd copyright infringement, you should mention any other projects, stackoverflow, videos, blogs, etc that you used to gather imagery or ideas for your code even if you used it as a starting point and modified things. Giving credit to other people's efforts and ideas that saved you time acknowledges the hard work others did.
- Code Institute Template
- The Template for the GUI for this project was provided by Code Institute. This allows for the Command line to be shown and used within the browser.
Use bullet points to list out sites you copied text from and cross-reference where those show up on your site
Make a list of sites you used images from. If you used several sites try to match up each image to the correct site. This includes attribution for icons if they came from font awesome or other sites, give them credit.
This is the section where you refer to code examples, mentors, blogs, stack overflow answers and videos that helped you accomplish your end project. Even if it's an idea that you updated you should note the site and why it was important to your completed project.
If you used a CodeInstitute Example project as a starting point. Make note of that here.