Created for Durhack 2022

By Tim Millard, Padgriffin, Charlie Simpson and Charlie Wilson

_{^{Additional help from @CarrotManMatt}}

1. Create a new branch to begin developing from by going to the branch management page of this repository and clicking the New branch button
2. Give your branch a suitable name and choose the most recently updated branch as the source (most often this will be the matt-changes branch)

• Pycharm (Preferred):

  3. Open/run Pycharm and close all currently open projects in order to return to the Welcome window
  4. Click the Get from VCS button in the top right corner of the window, then choose GitHub as the source on the left-hand side of the VCS pop-up window
  5. Log in to GitHub, then select the timmillard/durhack-2022 repository from the list
  6. Click the folder icon (🗁) on the far right-hand side of the Directory text-input box, then create a directory called Pulsifi in a location of your choosing, to store a local copy of the checked-out parts of the repository (THE DIRECTORY/PROJECT NAME MUST BE TYPED EXACTLY AS SHOWN in order to prevent errors with the workspace configuration files)
  7. Click the Clone button
  8. Open the Git Tool Window by clicking the Git button in the bottom left corner or using the alt+9 keyboard shortcut
  9. Right-click your newly created branch from the list under the Remote/origin folder and select Checkout to switch editing to your newly created branch
  10. Set up your workspace to use Django by:
      1. Going to: Settings/Languages & Frameworks/Django and selecting Enable Django Support (use the folder button (🗁) to navigate to the directory using the GUI)
      2. Choosing the root Pulsifi/ directory as the Django project root
      3. It will also be useful to configure the project structure (Go to: Settings/Project: Pulsifi/Project Structure):
         • Add the root Pulsifi/ directory to the list of Source Folders
         • Add the Pulsifi/staticfiles/ directory (if it exists) to the list of Excluded Folders
         • Add the Pulsifi/pulsifi/templates/ directory to the list of Template Folders
         • Add the Pulsifi/pulsifi/static/ directory to the list of Resource Folders
      4. Click the Apply button, then the OK button to save your changes
      5. Use the hide __init__.py scope by choosing it from the drop-down list in the top left of the project pane (it will say Project Files by default)
      6. Configure your python interpreter by clicking the default interpreter name (Python 3.11 (Pulsifi)) in the bottom right corner, then choosing: Add New Interpreter then Add Local Interpreter...
      7. Make sure the Environment is set to New, then click OK
      8. Wait for Pycharm to index the interpreter
      9. Open the Terminal pane by clicking the Terminal button in the bottom left corner or using the alt+F12 keyboard shortcut
      10. Install all the required packages for Pulsifi using this command: pip install -r requirements.txt (if an error appears, saying that pip could not be installed due to access being denied, it can be ignored, just make sure to run the command again)
  11. Create a file in the project's root directory called .env, any of the values from the supplied .env.example file can be added & configured (only EMAIL_HOST_PASSWORD, OATH_GOOGLE_SECRET, OATH_DISCORD_SECRET, OATH_GITHUB_SECRET, OATH_MICROSOFT_SECRET & SECRET_KEY are required)
  12. You need to migrate the python models to the database by:
      1. Opening the Run manage.py Task... pane, by selecting it from the Tools drop-down menu at the top or using the ctrl+alt+R keyboard shortcut
      2. Running these commands: makemigrations and migrate (it is also a good idea to run both of these commands, just in case, before committing any changes)
  13. You can now make the edits you desire to the code within your branch. (If you make any changes to the models.py file you will need to complete the above migration steps again)
  14. Any changes you do make will show up under the changes list, within the commit panel on the far left-hand side (also accessible by using the alt+0 keyboard shortcut). These changes can be committed to your branch then pushed to the remote repository by:
      1. Checking all the selection boxes next to any of the desired changed files in the changes list (only select files that you have purposefully changed. E.g. don't select pulsifi.iml or workspace.xml if these have been changed, but not by you)
      2. Typing a useful commit message in the Commit Message text-input box (see Robert Painsi's Commit Message Guidelines, for how to write good commit messages)
      3. Clicking the Commit and Push... button, to commit and push your changes to your branch
  15. To run the development server, select the Main Development run configuration, from the run configuration list in the top right corner, then click the green run arrow (▶), a browser window to the correct URL should open (if not navigate to http://localhost:8080 to view the site)
  16. To run the test suite, select the All Tests run configuration, from the run configuration list in the top right corner, then click the green run arrow (▶)

• VS Code:

  3. Now select your newly created branch from the list & copy the https download link using the green ˂˃ Code ▼ button
  4. Open/run VS Code and make sure the Python extension is installed, as well as the latest major version of Python
  5. Open the Source Control view panel by clicking the tree icon on the far left-hand side
  6. Select Clone Repository, and paste the copied repository URL into the Git: Clone prompt
  7. Select Clone from GitHub (this is usually the second option in the list dropdown), and authenticate your GitHub account with VS Code if necessary
  8. If the prompt still persists (and is asking for the Repository name), enter "timmillard/durhack-2022" to search for the repository, and select the correct one from the dropdown list
  9. Create a directory called Pulsifi in a location of your choosing, to store a local copy of the checked-out parts of the repository (THE DIRECTORY/PROJECT NAME MUST BE TYPED EXACTLY AS SHOWN in order to prevent errors with the workspace configuration files)
  10. Ensure your newly created branch is checked out for you to work on by making sure the name of your branch is shown below the settings cog in the bottom left corner
  11. Use the Ctrl+Shift+` keyboard shortcut to create and open a new terminal panel at the current directory
  12. Create and activate a new Python virtual environment using the py -3 -m venv .venv and .venv\scripts\activate commands (make sure these commands are run within the directory containing your local copy of the repository)
  13. Update the pip package with this command: python -m pip install --upgrade pip
  14. Install all the required packages for Pulsifi using this command: pip install -r requirements.txt
  15. Create a file in the project's root directory called .env, any of the values from the supplied .env.example file can be added & configured (only EMAIL_HOST_PASSWORD, OATH_GOOGLE_SECRET, OATH_DISCORD_SECRET, OATH_GITHUB_SECRET, OATH_MICROSOFT_SECRET & SECRET_KEY are required)
  16. You need to migrate the python models to the database by running these commands: py manage.py makemigrations and py manage.py migrate (it is also a good idea to run both of these commands, just in case, before committing any changes)
  17. You can now make the edits you desire to the code within your branch. (If you make any changes to the models.py file you will need to complete the above migration steps again)
  18. Any changes you do make will show up under the changes list, within the Source Control view panel on the left-hand side. These changes can be committed to your branch then pushed to the remote repository by:
      1. Adding them to the staging area, by clicking the plus (+) button next to any of the desired changed files in the changes list (only add files that you have purposefully changed, to the staging area. E.g. don't add pulsifi.iml or workspace.xml if these have been changed, but not by you)
      2. Typing a useful commit message in the Message text-input box (see Robert Painsi's Commit Message Guidelines, for how to write good commit messages)
      3. Clicking the checkmark at the top of the Source Control view panel, to commit your changes to your branch
      4. Clicking the refresh/pull/push/update button, on the status bar, in the bottom left corner next to your currently checked-out branch name, to push your commits to the remote repository
  19. To run the development server, use the py manage.py runserver localhost:8080 command, then navigate to http://localhost:8080 to view the site
  20. To run the test suite, use the py manage.py test command

• Using the Git Commandline & Your Favourite Text Editor:

  3. Now select your newly created branch from the list & copy the https download link using the green ˂˃ Code ▼ button
  4. Download and install the latest version of Git for Windows
  5. Create a directory called Pulsifi in a location of your choosing, to store a local copy of the checked-out parts of the repository (THE DIRECTORY/PROJECT NAME MUST BE TYPED EXACTLY AS SHOWN in order to prevent errors with the workspace configuration files)
  6. Open the Git-bash terminal and use the `cd` command to navigate to your newly created directory
  7. Once inside this directory execute the clone command to pull down the remote repository: git clone <YOUR GITHUB HTTPS LINK> (replace <YOUR GITHUB HTTPS LINK> with the link you downloaded in step 3)
  8. Switch to your newly created branch by using the checkout command: git checkout <YOUR NEW BRANCH NAME> (replace <YOUR NEW BRANCH NAME> with the name you chose in step 2)
  9. You now need to create a Python virtual environment by:
     1. Opening/running the Windows Terminal and executing these commands: py -3 -m venv .venv and .venv\Scripts\activate (make sure these commands are run within the directory containing your local copy of the repository)
     2. Updating the pip package with this command: python -m pip install --upgrade pip
     3. Installing all the required packages for Pulsifi using this command: pip install -r requirements.txt
  10. Create a file in the project's root directory called .env, any of the values from the supplied .env.example file can be added & configured (only EMAIL_HOST_PASSWORD, OATH_GOOGLE_SECRET, OATH_DISCORD_SECRET, OATH_GITHUB_SECRET, OATH_MICROSOFT_SECRET & SECRET_KEY are required)
  11. You need to migrate the python models to the database by running these commands: py manage.py makemigrations and py manage.py migrate within the Windows Terminal (it is also a good idea to run both of these commands, just in case, before committing any changes)
  12. You can now make the edits you desire to the code within your branch, using your favourite text editor. (If you make any changes to the models.py file you will need to complete the above migration steps again)
  13. Any changes you make can be committed to your branch by executing these commands within the Git-bash terminal: git add -A and git commit -m "<YOUR COMMIT MESSAGE>" (replace <YOUR COMMIT MESSAGE> with a suitable message for the changes you have made, see Robert Painsi's Commit Message Guidelines, for how to write good commit messages)
  14. To run the development server, open/run Windows Terminal and use the py manage.py runserver localhost:8080 command, then navigate to http://localhost:8080 to view the site
  15. To run the test suite, use the py manage.py test command

• Always use double quotes, unless inside an HTML template variable string within an HTML tag attribute (E.g. <a href="{% url 'default' %}"></a>)
• Never put commas after the last item in a list/dictionary (E.g. ["a", "b", "c"], not ["a", "b", "c",]). Only add a trailing comma in a tuple with only one element (E.g. ("username",))
• Model names are capitalised (E.g Post)
• View names are capitalised, end in View and have words seperated by underscores (E.g. Feed_View)
• Constants, settings values and field choices are uppercase and have words seperated by underscores (E.g. STATIC_URL)
• Model field names are lowercase, must not contain the model name and have words seperated by underscores (E.g. date_time_created, not postDateTimeCreated)
• HTML template names are lowercase and have words seperated by underscores (E.g. feed.html)
• Use docstrings on all classes and public methods to help others understand code functionality
• Use the django-admindocs format to refer to models/views/templates (E.g. This is a :model:`pulsifi.pulse` object.)
• All comments should be on the same line as the code being referenced, and should use this format: <code>··#·<mnemonic>:·<comment> (E.g. print("Hello")  # TODO: Output username)
• Comment mnemonics must be one of the example values specified in the CodeTags style documentation
• Docstrings and type hinting is preferred over using the NOTE mnemonic in a comment
• Temporary comments do not have to include a mnemonic
• Pycharm inspection suppression comments do not have to include a mnemonic and are placed on the line above the code that they are surpressing (See this gist for the full list of available suppression comments)
• Be very cautious when using QuerySet.update(), as this will *NOT* execute the save() method of each object instance (which is essential to ensure data integrity & validity). There are unlikely to be cases where the performance decrease of using the custom Custom_Model.update() method, on each instance individually, is so significant that QuerySet.update() has to be used. If in doubt, iterate through each instance with a for loop, and call Custom_Model.update() individually.
• Never use any bulk edit functions (E.g. QuerySet.delete(), QuerySet.bulk_create(), QuerySet.bulk_update(), etc.), as these will not execute the respective, overridden Model.save() or Model.delete() methods (which is essential to ensure data integrity & validity).
• Always add full-stops to the end of Exception messages & Docstrings (E.g raise ValidationError("That value is invalid.") and """ This function returns an int. """)
• Every file should end with an empty line
• Every python module should start with a module-level docstring, seperated from the python code below it by a single blank line
• Never import individual functions/variables from another package/module. Always import the whole package/module so that the global namespace does not get diluted (E.g. from django.contrib import admin (using admin.site later on), not from django.contrib.admin import site)
• If there is a high likelihood that modules with similar names will be imported from multiple packages, the imports should use an alias that contains the package name (E.g. from core.urls import utils as core_url_utils and from django import urls as django_urls)
• Classes should be imported individually from modules/packages (E.g. from typing import Iterable, not import typing (using typing.Iterable later on))