README.md

Why have a README.md File?

A README.md file is the front-page introduction to a GitHub repository and the first thing visitors see when they open your repo. For any software, it is really handy to have notes to refer back to highlighting key parts of your software or webapp along with evidence of all your hard work and testing. A good README.md helps other developers quickly understand the webapp, reduces onboarding time, and makes the project more professional and accessible.

It is written in markdown (hence the .md file extension) so follows some similar syntax as HTML; just simplified. A good description of all the syntax that you will need can be found here in the GitHub documentation.

Some further example syntaxes that I use regularly are:

Add in an image with:

![Alt text](/path/to/image)

Add in a horizontal rule to split up sections with:

---

External links:

Internal links to sections with a heading. Here the heading-name is the name of the heading with all spaces replaced with hyphens. Also, even if it is a heading 2 or heading 3, you only need one pound symbol (#) for the link.

Table:

|Column 1 title | Column 2 title | Column 3 title |
| --- | --- | --- |
| Column 1 row 1 | Column 2 row 1 | Column 3 row 1 |
| Column 1 row 2 | Column 2 row 2 | Column 3 row 2 |

Bold text:

**Bold text**

Line break:

<br>

Drop down sections used mainly to hide large images so as to not crowd the document.

<details><summary>Dropdown title</summary><img src="/path/to/image.png"></details>

The general syntax is a summary element nested inside a details element.

<details><summary>Title of dropdown</summary>Dropdown content</details>

Setting up the README

When you set up your repository, you can select an option to have a README.md file created by default. If not, simply create a README.md file in your root directory and GitHub will automatically detect and display it under your file layout on your repository page.

README.md Sections

The README.md file can contain lots of sections and many may not be applicable to your own application. Listed and discussed here are the ones that I often find myself including. For larger README.md files, I split them across smaller specialised files.

  • README.md - To handle the outline of the project, technologies used, accreditations, and acknowledgements. Possible sections include:
    • Project Goals (User Goals, Site Owner Goals, Developer Goals)
    • User Stories
    • Security (Defensive Programming, Validation)
    • Future Development
    • Technologies Used (Languages, Frameworks, Libraries and Packages, Tools)
    • User Feedback
    • Credits (images and other)
    • Acknowledgements
  • DESIGN.md - To handle the five stages of UI/UX and the site features
  • TESTING.md - To document all the site testing
  • DEV.md - To document the continuous development and deployment of the website

Some things that they all have in common are an image of the website brand at the top, a title, links and descriptions to the other README files and a contents section.

Template

README.md


![Website logo](/documentation/site_logo.png)
---
A paragraph describing the webapp. Include
-	The type of website (full stack/ front end etc.)
-	Purpose
-	The intended audience(s)
-	Which languages were used to create the website along with the major tools/frameworks
-	How it is hosted and how static files are hosted
-	A description of the type of database if used and the value that the databases add to the user experience
The live site can be viewed [here](https://deployedwebsiteaddress.com/)
See [DESIGN.md](/DESIGN.md) for information on the five planes of UX design, site map, database schema, and features. <br>
See [TESTING.md](/TESTING.md) for information on the test driven development of the website, manual and automated testing of the site, bugs encountered, and website analytics. <br>
See [DEV.md](/DEV.md) for an overview of the continuous integration and deployment process, how I set up my development environment, and deployment steps.

---

## Table of Contents
1. [Project Goals](#project-goals)
    1. [User Goals](#user-goals)
    2. [Site Owner Goals](#site-owner-goals)
    3. [Developer Goals](#developer-goals)
2. [User Stories](#user-stories)
3. [Security](#security)
    1. [Defensive Programming](#defensive-programming)
    2. [Form Validation](#form-validation)
4. [Future Development](#future-development)
5. [Technologies Used](#technologies-used)
    1. [Languages](#languages)
    2. [Frameworks](#frameworks)
    3. [Libraries and Packages](#libraries-and-packages)
    4. [Tools](#tools)
6. [User Feedback](#user-feedback)
7. [Credits](#credits)
    1. [Images](#images)
8. [Acknowledgements](#acknowledgements)

## Project Goals
### User Goals
- A website that is easy to navigate.
- A website that will display well on different devices.
- Positive and immediate feedback from the site such as on hover or on click JavaScript animations to ensure a good user experience.
- Contact information of the developer.
- Site specific goals.
### Site Owner Goals
- Provide a website that is safe for users to sign up to and that their data is handled securely.
- Site specific goals.
### Developer Goals
- A well designed website that catches the attention of the users.
- A responsive website where the functionality is not impacted by screen size.
- Easy navigation that is intuitive and responsive.
- A website designed with accessibility in mind.
- A finished product that will proudly be displayed within the developer's portfolio.
- Site specific goals.

## User Stories
| User Story ID | As A/An | I Want To Be Able To... | So That I Can... |
|-----|------|-----|-----|
|<td colspan="4">**Viewing and Navigation**</td>|
| 1 | First Time Visitor | Tell the purpose of the website immediately | Decide whether I want to use the website |
| 2 | First Time Visitor | Navigate the website easily and intuitively | I can find the content that I need |
| 3 | First Time Visitor | Know that my interactions on the website have worked | Be sure that the website is resposinsive |
|<td colspan="4">**Site Specific e.g. Registration and User Accounts or Searching or Payment **</td>|
| 4 | Site User | Have the site content to be safe and secure | Know that I am not open to any malicious activities |
| 5 | Potential Customer | Filter and sort the products| Find the best product for me |
| 6 |Customer | Easily enter my payment information | Check out quickly and with no hassles |
| 7 | Business Owner | See reviews | Improve as a business |

## Security
Here list the key security methods employed to make your website safe for it's users. An example of this is your .gitignore file
**.gitignore**<br>
Describe the reason behind the .gitignore file and then list the 
One of the security steps taken was to put all sensitive and irrelevant information in the .gitignore file so as to not upload them to the public online repository. Those added to this file were:
| Inclusion in .gitignore | Reasoning |
|-----|-----|
| venv | It has the virtual environment information including paths and configurations that won't work for other developers or environments. So it was added to .gitignore to reduce redundancy and clutter in the repository. |
| env.py | To hide sensitive information such as… |
**Django Allauth**<br>
AllAuth is an open source Django package that I used to handle user authentication on the website. It is open source, so it is backed by millions of developers who keep it up to date and secure, providing a key part in the security of this website and data-security of the users who will create user accounts with us. The client ID and secret keys for the social sign-ins are kept in the secure admin dashboard.
**crsf tokens**<br>
These are present in all forms on the website, preventing from Cross-site Request Forgery attacks, confirming that the form is submitted by a real user, not a malicious third party.
**Password Security**<br>
Django AllAuth uses the password hashing algorithm PBKDF2 to hash passwords before storing them, allowing them to be stored securely and for the possibility for multiple users to have the same password without impacting site security.
**Email Validation**<br>
As a part of Django-allauth, email validation is required to prevent fake accounts, verify ownership of the email address, and to reduce phishing risks.
**External links**<br>
All external links open in a new tab and have rel="noopener" to prevent the opened page from accessing the pages on this website, increasing security.
**Access required**<br>
On certain pages, the view only loads the page if the user is a superuser or is logged in depending on the requiremnet.

### Defensive Programming
Here list all the defensive programming steps you implemented such as password confirmation, email login, logout pages, form elements, delete confirmation pop ups etc.
**Password confirmation**<br>
The signup form requires a confirmation of the password to prevent the user from making a typo.

### Form validation
Here describe how your form validation is handled throughout the website. 

## Future Development
Here you can list all the extras you thought of during development that would build upon your completed website.

## Technologies Used
Here list the technologies you used including a link to them in possible and what they were used for. The libraries and packages section should also describe everything in your requirements.txt file if you have one.

### Languages
- [HTML](https://en.wikipedia.org/wiki/HTML)
    - Markup language used for website structure.
- [CSS](https://en.wikipedia.org/wiki/CSS)
    - Used for styling the elements on the webpage.
- [JavaScript](https://en.wikipedia.org/wiki/JavaScript)
    - Used for dynamic functionality on the website.
- [Python](https://www.python.org/)
    - Used for server side scripting and backend development.
- [SQL](https://en.wikipedia.org/wiki/SQL)
    - Used for maintenance and querying of database throughout to confirm correct functionality.

### Frameworks
- [Django](https://www.djangoproject.com/)
    - Django is a full server-side framework used to build this web app. It is written in python and provides batteries and low-level automation that makes it easier to build a better web app with less code.

### Libraries and Packages
- [Pip](https://pypi.org/project/pip/)
    - The package installer for python used to install packages and libraries.
- [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/)
    - Used for some styling and site functionality

### Tools
- [Visual Studio Code](https://code.visualstudio.com/)
    - This is my IDE of choice for writing my HTML, CSS, JavaScript, and Python code for this project
- [Git](https://git-scm.com/)
	- Used for version control.
- [GitHub](https://github.com/)
	- Used to store the code in a Repository

## User Feedback
Include some user feedback from either the business owner or even your friends and family during development. Describe who gave it and list them and whether they were included or not. If not, explain why.

## Credits
List any videos or tutorials you made use of.
[Description](https://link.com) and describe how you used the video to help you.

### Images
List which images were yours and the for others describe where they were used in the website and who has ownership of them, how you got permission to use them and then link the photographer/designer.

## Acknowledgements
Acknowledge any people, colleagues, friends, or family that helped and supported you.

DESIGN.md


![Website logo](/documentation/site_logo.png)
---
# Design
See [README.md](/README.md) for information on project goals, user stories, security, future developments, technologies used, user feedback, credits, and acknowledgements. <br>
See [TESTING.md](/TESTING.md) for information on the test driven development of the website, manual and automated testing of the site, bugs encountered, and website analytics. <br>
See [DEV.md](/DEV.md) for an overview of the continuous integration and deployment process, how I set up my development environment, and deployment steps.

---
## Table Of Contents
1. [Five Planes of UX](#five-planes-of-ux)
    - [Strategy](#strategy)
        * [Viability and Feasibility](#viability-and-feasibility)
    - [Scope](#scope)
        * [Back-end](#back-end)
        * [Front-end](#front-end)
    - [Structure](#structure)
        * [base.html](#basehtml)
        * [index.html](#indexhtml)
        * [allauth](#allauth)
        * [search_results.html](#search_resultshtml)
        * [trips.html](#tripshtml)
        * [cancel_trip.html](#cancel_triphtml)
        * [checkout.html](#checkouthtml)
        * [account_settings.html](#account_settingshtml)
        * [delete_account.html](#delete_accounthtml)
        * [rooms.html](#roomshtml)
        * [Information Architecture](#information-architecture)
        * [Interactive Experience](#interactive-experience)
    - [Skeleton](#skeleton)
        * [wireframes](#wireframes)
    - [Surface](#surface)
        * [Colour Scheme](#colour-scheme)
        * [Typography](#typography)
        * [Images](#images)
2. [Features](#features)

## Five Planes of UX
Describe your philosophy when it came to following the five planes of UX/UI and your design process for this webapp. Describe the benefits of doing it this way.
### Strategy
- **What value does the project provide?** Answer the question
- **What are the business needs?** Answer the question
- **Who is the target audience?** Answer the question
- **What are the user requirements and expectations?** Answer the question
#### Viability and Feasibility
Describe your viability and feasibility analysis of the user stories and user and business needs ranked from 1 (least important/viable) to 5 (most important/viable):
|   Task |   Importance | Viability/Feasibility |
| --------- | ------------- | ----------------- |
| First row example | 5 | 5 |
Describe the above rankings highlighting key areas you will meet (high importance), those that will be met if there is time (low importance, high viability/feasibility OR mid importance, mid viability/feasibility) and those that are not important or are unfeasible. Give reasons for each.

### Scope
#### Back-end (If back-end)
Describe the type of database and if it will meet the requirements for your project.
List the models or tables required
- **Example Model**: Describe how it will be implemented, what fields it will have and which will have the function to be queried and why.
#### Front-end
Describe how your website will be built and the benefits of doing it that way. Then describe the templates with a list of requirements, refer back to user stories and user and business needs.
**Templates**
- **base.html**: This will be the base template that the others call from to ensure a cohesive structure across the website. It will have:
    - All the header meta information
    - Links to styling and JavaScript scripts
    - The header with the site logo, a booking form, and account navigation links
    - The footer with the hotel social media links, hotel contact information, the site logo, and developer contact information

### Structure
Here list your pages and describe their features and which requirements they meet. Here is an example for a baste template for a hotel management website. Do this for all of your pages.
#### base.html
- As the base template, this will have the site-wide navigation bar and footer
- The navigation bar will meet the requirement for intuitive and responsive navigation, consisting of a site logo, booking form on large screens, and account links. When logged out the links will be to Sign Up / Login. When logged in the links will be to Trips / Account Settings / Logout. When logged in as a Super User the links will be to Rooms / Trips / Account Settings / Logout.
- The footer will meet the requirement for the hotel and developer contact information and will consist of the hotel social media links, contact information for the hotel and developer, and site logo.
#### Information Architecture
**Back-end**: Entity Relationship Diagram (ERD) <br>
Include a proposed ERD for your backend. 
![ Entity relationship diagram](/documentation/entity_relationship_diagram.png)<br>
**Explanation**
- Explain how the relational or non-relational database works
-  Go through each model describing the fields, why they were chosen and how they add value.
#### Interactive Experience
List all the functions for interactive experiences for the user that you will include. Some that you should include are:
- Clickable links will have animated effects on hover or click, providing clear feedback to the user.
- All external links will open in a new tab. 
- Content hinting will be used where possible to influence the user to scroll down and uncover new content on the pages.

### Skeleton
#### Wireframes
Describe how you produced the wireframes with a link to the software if used. <br>
Link to a separate page to display all desktop wireframes [here](/documentation/wireframes_desktop.png). <br>
Where there were major differences, link to a separate Mobile Wireframes page [here](/documentation/wireframes_mobile.png).<br>

### Surface
#### Colour Scheme
Describe your colour scheme and the inspiration behind it. Remember to include colours used for success or errors too.
![Image of your colour palette](/documentation/colour_palette.png)
Then list your colours and what they are used for. For example:
**Jasmine #FDD67C**
- Font colour on Fern Green backgrounds
- Background to the navigation bar form inputs
- Button backgrounds (normal)
- Button text (hover)
- Golden halo for button hover animations
- Account menu background (normal)
- Account menu background (hover)

#### Typography
Describe the effect you want to portray with your chosen typography. Aim for at least 2-3 fonts. Then list them below like:

**[Font Name](https://fonts.google.com/specimen/chosenfont)**<br>
![Screenshot of the font](/documentation/typography_fontname.png)<br>
Describe how this font is used and what about it makes it fit for purpose. Then list the backup fonts e.g. As a sans-serif font, the backup fonts were Arial, Helvetica, and sans-serif.

#### Images
Here list the images you used, how they were created and give credit where credit is due. Remember to include icons such as those from Font Awesome.

## Features
Here list all the features on all your pages. Include what they are, what pages they appear on, an image of them, the purpose of them and which user stories are covered. Below is an example of a site logo.
| **Site Logo** |
| ----- |
| **Page: All - Header and Footer** |
| <details><summary>Site Logo</summary><img src="/documentation/features/site_logo.png"></details> |
| **Details:** The site logo conveys the brand of the website, immediately highlighting which website that the user is on, and acts as a link back to the homepage. |
| **User Stories Covered:** 1, 2 |

TESTING.md


![Website logo](/documentation/site_logo.png)

---

# Testing
Define manual testing, automated testing, and their differences. Explain your philosophy when it came to testing your webapp.
If using the TDD approach, explain it and give an example. 
Explain your process when you implement new functionality.
Describe any testing software that you used.

See [README.md](/README.md) for information on project goals, user stories, security, future developments, technologies used, user feedback, credits, and acknowledgements. <br>
See [DESIGN.md](/DESIGN.md) for information on the five planes of UX design, site map, database schema, and features. <br>
See [DEV.md](/DEV.md) for an overview of the continuous integration and deployment process, how I set up my development environment, and deployment steps.

---
1. [Testing User Stories](#testing-user-stories)
2. [Manual Testing](#manual-testing)
3. [Device and Browser Testing](#device-and-browser-testing)
4. [Automated Testing](#automated-testing)
    - [Test Driven Development](#test-driven-development)
    - [Accessibility Testing](#accessibility-testing)
    - [Performance Testing](#performance-testing)
    - [HTML Validation](#html-validation)
    - [CSS Validation](#css-validation)
    - [JavaScript Validation](#javascript-validation)
    - [Python Validation](#python-validation)
5. [Bugs](#bugs)
    - [Bug 1](#bug-1)
    - [Bug 2](#bug-2)
    - [Bug 3](#bug-3)
    - [Bug 4](#bug-4)
    - [Bug 5](#bug-5)
    - [Known Bugs](#known-bugs)
7. [Analytics](#analytics)

## Testing User Stories
The [user stories](/README.md#user-stories) have been a driving force for the development of this project. More information on each user story and how the features implemented in this web app meet their criteria can be seen [here](/DESIGN.md#features). Most user stories were met to create a MVP, however future development will include adding form elements to the checkout to allow users without an account create one and save their order.

## Manual Testing
Here tabulate your features and how you manually tested them from the point of view of a user. You should include what the feature is, the action you performed, what result you expected and whether your test passed. Include some comments if necessary and link it to your bug section if you encountered a bug that you either fixed or still persists. Some may look like:
| Feature | Action | Expected results | Passed | Comments |
| ----- | ----- | ----- | ----- | ----- |
| **base.html** | | | | |
| Site logo - header | Click | Redirected to the homepage | Y | N/A |
| Site logo - footer | Click | Redirected to the homepage | Y | N/A |
| Booking form | Submit with empty fields | Prompt to enter a check in date | Y | N/A |
| Booking form | Submit with only check in date | Prompt to enter a check out date | Y | N/A |
| Booking form | Submit with dates and no guests | Prompt to add guests | N | [Bug 1](#bug-1) highlighted and fixed |
| Booking form | Submit with dates and no guests | Prompt to add guests | Y | N/A |
| Booking form | Click check in/check out | Calendar widget appears to select dates with a golden halo on the widgets | Y | N/A |
| Booking form | Open check in/ check out calendar widgets | Dates in the past are disabled | Y | N/A |
| Booking form | Open check in/ check out calendar widgets | Dates over a year away are disabled | Y | N/A |

## Device and Browser Testing
Describe your responsiveness testing on your development laptop/desktop and any mobile phones you have. List the emulated screens from Google Chrome Devtools. A good idea here is to go down to the iPhone 5/SE screen size as it is one of the smaller smart phones in use today. List these screen sizes here:
- iPhone SE (375px x 667px)

## Automated Testing
### Test Driven Development
If using TDD, describe it here and explain any libraries used to test your site such as coverage for Django webapps. Include how it was installed, run, and link to any reports it generated.
Describe any reports; what the results were, and give explanations for areas that did not meet 100%.
### Accessibility Testing
Here describe how you kept to the accessibility best practices during development (aria-labels, alt texts, semantic HTML, colour contrasts, hiding text in a way that was still accessible to screen readers etc).
Describe how accessibility testing was performed (e.g. WAVE). Link to the tester and describe it's use.
Then go through each page showing any errors or alerts that were thrown up and explain them in they were not fixed. Include a screenshot of the report. An example may look like:
**Base Template**<br>
- 2 Low contrast errors: These appear because wave does not recognise the position of the check in/ check out labels being as being form-floating inside the inputs so incorrectly computes the contrast against the header background, not the input background. This error in the wave validation is carried over to every page of the website as they all extend from this base template. These errors do not affect the usability of the website and are ignored when they appear.
- 1 alert for no heading structure. This is because a H1 element is not used within the base template. As each page inherits from this template, they will have their own H1 headings, so this alert only occurs when testing the base template in isolation and thus is ignored going forward.
<details>
<summary>Base template results</summary>
<img src="/documentation/testing/wave/base.png">
</details><br>
### Performance Testing
Describe the performance testing e.g. using Lighthouse within the Google Chrome Devtools. List the steps taken during development to ensure the best performance e.g. image optimisation, code minification, caching files, lazy loading etc.
Include screen shots of the performance reports and explain any areas that did not perform as well as expected.
### HTML Validation
Describe and link to your HTML validator and how you used it. Tabulate each page with warning and errors explain; such as:
| Page | Warnings | Errors |
| ----- | ------ | ------ |
| Base template | None | None |
| Back button | None | None |
### CSS Validation
Describe the CSS validator you used and explain the results. Include screenshots of the results for each page similar in style to the accessibility testing results.
### JavaScript Validation
Describe the JavaScript linter you used and discuss the results. Provide a description of what code was tested and the setup of the linter in each case and your results. For example for JSLint:
**Base template**<br>
- The base.js file was copied into the linter and the postload JavaScript at the bottom of base.html was added to this for the purpose of validation. 
- The following linter settings were selected: browser, this. 
- The following variables were added: bootstrap.
- No warnings.
- Full results can be seen [here](/documentation/testing/jslint/base_template.pdf)
### Python Validation
Describe and link the standard to which your Python code was held to (PEP8). Also describe and link your python linter of choice. For the results; state the file name, describe any errors or alerts and include a screenshot of the results, such as:
**Project: settings.py**<br>
- No errors or alerts
<details>
<summary>Settings results</summary>
<img src="/documentation/testing/python/project_settings.png">
</details><br>

## Bugs
Write down major bugs your found during development, how they could be reproduced and how they were fixed. Include code snippets or screenshots where useful. At the end list any current known bugs with how they can be reproduced and your proposed process to fix them going forward.

## Analytics
Describe any analytics systems used on your webapp and what data they will show you. Mention how this data will be used to aid your continued development and go through the steps you took to set it up.

DEV.md


![Website logo](/documentation/site_logo.png)

---

# Development and Deployment

See [README.md](/README.md) for information on project goals, user stories, security, future developments, technologies used, user feedback, credits, and acknowledgements. <br>
See [DESIGN.md](/DESIGN.md) for information on the five planes of UX design, site map, database schema, and features. <br>
See [TESTING.md](/TESTING.md) for information on the test driven development of the website, manual and automated testing of the site, bugs encountered, and website analytics. <br>

---
## Table Of Contents
1. [CI/CD](#cicd)
2. [Development Environment](#development-environment)
    - [Creating a GitHub Repository](#creating-a-github-repository)
    - [Cloning the GitHub Repository Locally](#cloning-the-github-repository-locally)
    - [Setting up my IDE](#setting-up-my-ide)
    - [Project Requirements](#project-requirements)
    - [Getting the Project up and Running](#getting-the-project-up-and-running)
    - [Coding in Python and PEP8](#coding-in-python-and-pep8)
3. [Local Development](#local-development)
4. [Apps](#apps)
5. [Deployment](#deployment)

## CI/CD
Describe your philosophy of continuous integration and continuous deployment.
Describe what version control you used (Git) and how your code was stored (GitHub). Describe the difference between version control and continuous integration  (Though not strictly continuous integration, version control and continuous integration are synergistic and have a large overlap in terms of project management). Was the repository shared, if so, why?
Link to any project planning/tracking software used such as GitHub projects.

## Development Environment
List the steps that you took to set up my local development environment in order to provide guidance to unfamiliar users with how to set up their own local development environment. 
### Creating a GitHub Repository
Steps for this
### Setting up my IDE
Steps for this
### Building a Virtual Environment
Steps for this
### Project Requirements
List these and how to install them. Link to your requirements.txt file.
### Getting the Project up and Running
Steps for this
### Coding in Python and PEP8
State how you kept to PEP8 for Python coding

## Local Development
Describe how someone could install your project locally such as:
To install my project locally, you can follow my steps above in the [Development Environment](#development-environment) section, replacing file and folder names with the ones in my project.
You can also fork the GitHub repository to collaborate by once logged into GitHub by:
- Go to the repository for this project, [project_name](url).
- Click the Fork button in the top right corner and create a new fork.

## Apps
For Django projects list how your functionalities were split into apps in order to maximise the readability and reusability of the code. Describe how the correct guidelines were continuously being met throughout the project such as adopting some checklists for each file I added. Give an example of this.
Then list your apps and what functionality or features they hold.

## Deployment
Describe your deployment process