Merge branch 'master' into task-when-to-new-repo

docs/Using-GitHub.md

@@ -1,3 +1,5 @@
+This is an EDIT
+
 # Using Git Hub to Contribute to GIS Pantry (My Change)
 
 [Home](./getting-started-with-QGIS/README.md)

docs/__gis-pantry-intro-docs__/GitHub_Account_Set_Up.md

@@ -0,0 +1,53 @@
+| Status      | Draft             |
+|-------------|-------------------|
+| Last Update | 2023-07-21        |
+| Tags        | #GitHub, #account |
+| Improvements| yada yada  |
+
+# Git Hub Account Set-up / Configuration
+If you want to contribute to the GIS Pantry, you will need a GitHub account. If you already have an account, then skip to [account configuration](#account-configuration). If you do not have an account then start below.
+
+Helpful Resources:  
+[Account and profile documentation on GitHub](https://docs.github.com/en/account-and-profile)
+
+## Create a New Account <a name="account_create"></a>
+### Step By Step
+1. You can [sign up here](https://github.com/)
+    - Click "Sign up" and enter your government email. 
+        ![image](./_media/GitHub_account_InitialSignupPage.PNG)  
+        *You will be able to add additional emails later if you want.*
+1. Follow the prompts to create your new account.
+    - You may name your account as you wish. The general recommendation is to use your name, however many use a handle. 
+    - If you use a handle, you may want to set your display name to your real name so that others know who you are. You can change your display name later without affecting anything.
+1. Next you will set up some basic account configurations...
+
+## Account Configuration
+We recommend the following account changes before contributing to the GIS Pantry, or taking other BCGov related actions.
+
+*For further info on this section see the BCGov GitHub Organization guidelines [here](https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Gov-Org-HowTo/Joining-the-BCGov-on-GitHub.md)*
+
+1. To Begin...  
+    * First, log into your account
+    * After you have logged in, go to your account icon in the upper right corner
+    * Then click settings. ![image](./_media/GitHub_account_OpenAccountMenu.PNG) ![image](./_media/GitHub_account_GoToAccountSettings.PNG)
+
+1. Now configure your emails...  
+    1. Click >> Emails
+        - Add any emails you want
+            - Be sure to include your government email.    
+        - You can also choose which email is your primary.
+        ![image](./_media/GitHub_account_EmailSettingsClarified.PNG)
+1. Finally, set up your public profile...  
+    1. Click >> "Public Profile"
+        - Update your display name (optional)  
+        *This helps if you signed up for your account with a handle, rather than your real name. Changing your display name allows your colleagues to easily recognize you. You may change this later.*
+        - Set Company to "Province of British Columbia"
+        - You can also choose an email to display publicly...
+        - You can make other changes as desired. Like adding a bio ![image](./_media/GitHub_account_BasicProfileInfoPNG.PNG)
+
+1. Join the BCGov GitHub organization (OPTIONAL)  
+*You do not need to do this to contribute to the pantry. You can still contribute by forking the Pantry, and then submitting a pull request. Joining the org provides you additional permissions...*  
+
+    [Instructions to join](https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Gov-Org-HowTo/Joining-the-BCGov-on-GitHub.md)  
+
+.... **Your account is ready to go!**

docs/__gis-pantry-intro-docs__/GitHub_DesktopApplication.md

@@ -0,0 +1,30 @@
+---
+id: my1mi6ji61idls167ooq4qh
+title: GitHubDocs
+desc: ''
+updated: 1698957503858
+created: 1698957442570
+---
+1. **Install GitHub Desktop:** Visit the [GitHub Desktop website](https://desktop.github.com/) and download the app for your operating system. Install it on your computer and sign in with your GitHub account.
+
+2. **Clone a repository:** After signing in, you can clone a repository by clicking on the "Clone a Repository from the Internet" button on the GitHub Desktop app's home screen. Alternatively, you can go to the "File" menu and select "Clone Repository."
+
+   - Choose the repository you want to contribute to: You can search for a repository by its name or use the provided URL. Once you've selected the repository, choose a local path where the repository will be cloned on your computer.
+
+   - Click on the "Clone" button to initiate the cloning process. The repository will be downloaded to your chosen location.
+
+3. **Create a new branch:** In GitHub Desktop, select the repository you cloned from the left sidebar. Then click on the "Current Branch" dropdown button, and choose "New Branch." Give your branch a descriptive name that reflects the changes you plan to make.
+
+4. **Make changes:** Use your favorite code editor or file explorer to make the necessary changes to the files within the cloned repository on your computer.
+
+5. **Review changes:** Go back to the GitHub Desktop app. You should see a list of changed files under the "Changes" tab. Review the changes you made and ensure they are correct.
+
+6. **Commit changes:** To commit your changes, provide a summary of the changes made and an optional description in the "Summary" and "Description" fields, respectively. It is recommended to keep commits focused on a single logical change. Click on the "Commit" button to save your changes to the local branch.
+
+7. **Push changes to GitHub:** After committing your changes, you need to push the changes to the remote repository on GitHub. Click on the "Push origin" button in the upper-right corner of the GitHub Desktop app. This action will send your committed changes to the remote repository on GitHub.
+
+8. **Open a pull request:** Once the changes are pushed to the remote repository, you can open a pull request on GitHub to propose your changes for review. In GitHub Desktop, you can click on the "Create Pull Request" button in the lower-right corner of the app to open the repository on the GitHub website and create a pull request there.
+
+9. **Provide details for the pull request:** On the GitHub website, provide a descriptive title and additional comments to explain your changes. Review the changes and make sure everything looks good before submitting the pull request.
+
+10. **Submit the pull request:** Click on the "Create pull request" button to submit your pull request. Your changes will now be available for review by the repository maintainers, and you can continue the discussion and make further changes as needed.

docs/__gis-pantry-intro-docs__/GitHub_Markdown.md

@@ -0,0 +1,69 @@
+# What is Markdown and How To Use It
+
+## What is Markdown???
+
+> Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages. - [Markdown Guide](https://www.markdownguide.org/getting-started/)
+
+Markdown is a plain text formatting syntax. It is used to create websites, documents, notes, books, presentations, emails, and technical documentation. GitHub uses GitHub Flavored Markdown ([GFM](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)) which is a strict superscript of [CommonMark](https://commonmark.org/) (a rationalized version of Markdown syntax). Although Markdown has its syntax, HTML, JavaScript, and GeoJson elements and tags can also be used to format your text and create diagrams and visualizations. More information on Markdown can be found [here](https://www.markdownguide.org/getting-started/)
+
+---
+
+## How to use Markdown
+Markdown files are saved as a .md extension, then using plain text and markdown [syntax](https://www.markdownguide.org/cheat-sheet/), the document is formatted
+
+>#### <u>Example Code</u>
+>```
+># Heading
+>Headings are represented by the # symbol and the number of #'s used represents the heading level
+>
+>## Heading 2 
+> If the following elements are used they will produce horizontal a horizontal rule
+>
+>---
+>***
+>
+>### Heading 3
+>Text formatting can use Markdown or HTML, for example 
+>- *Italic* or <i>Italic</i> <br>
+>- while **can represent bold** or <b> can represent bold</b>
+>- Markdown does not include a built-in <u>underline</u> element but HTML tags support <ins>underlines</ins> with different ways to produce the same effect
+>```  
+<br>
+<br>
+
+>#### <u>Example in Markdown</u>
+>
+># Heading
+>Headings are represented by the # symbol and the number of #'s used represents the heading level
+>
+>## Heading 2 
+> If the following elements are used they will produce horizontal a horizontal rule
+>
+>---
+>***
+>
+>### Heading 3
+>Text formatting can use Markdown or HTML, for example 
+>- *Italic* or <i>Italic</i>
+>- while **can represent bold** or <b> can represent bold</b>  <br>
+>- Markdown does not include a built-in <u>underline</u> element but HTML tags support <ins>underlines</ins> with different ways to produce the same effect
+>
+---
+ 
+
+A quick start guide to using Markdown in GitHub can be found [here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github)
+
+The [Writing on GitHub](https://docs.github.com/en/get-started/writing-on-github) documentation is a great resource and covers topics on [starting to write on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github), [advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting), [saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies), and [editing and sharing content with gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists). There are many great resources available for GFM and markdown below are a few of our favorites. 
+
+
+## References and Guides
+|Title|URL|
+|---------------|---------------|
+|GitHub Docs: Writing on GitHub|https://docs.github.com/en/get-started/writing-on-github|
+|GitHub Flavored Markdown Spec|https://github.github.com/gfm/|
+|Markdown Guide|https://www.markdownguide.org|
+|HTML Cheat Sheet|https://quickref.me/html.html|
+|Mermaid: Diagrams and Visualizations|https://mermaid.js.org/intro/|
+|Table Convert|https://tableconvert.com/|
+
+

docs/__gis-pantry-intro-docs__/GitHub_Searching.md

@@ -0,0 +1,22 @@
+# Searching in GitHub
+*How to search for organizations, repositories, code, commits, issues, packages, topics, wikis and user*
+
+## Further Reading
+- [Getting Started with Searching On GitHub](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/about-searching-on-github)
+- [Dev Tips: Searching GitHub Like a Pro](https://medium.com/cloud-native-the-gathering/dev-tips-searching-github-like-a-pro-5de2e73cba3d)
+- [GitHub Search Tips](https://www.freecodecamp.org/news/github-search-tips/)
+
+## Prerequisites 
+* Signed in to GitHub
+
+
+## Introduction
+There are two primary ways to search GitHub: the search bar on the top of the website and the advanced search. Your search can be focused globally or on a particular repo or organization. Repositories, Topics, Issues and Pull Requests, Discussions, Code, Commits, Users, Packages and Wikis can all be searched. Advanced searches can be done through the [visual interface](https://github.com/search/advanced).
+
+## Basic Search
+If we search "GIS Pantry" in the search bar on the top of the GitHub website, first, we get thousands of pieces of code that include the word pantry. We can navigate to repositories using the filtering options on the left side and see the GIS Pantry repository. If we continue with the filters, we can see what issues, pull requests, commits and wikis are associated with a name or tag GIS Pantry
+ ![Alt text](_media/Github_Search_image_1.png)
+
+## Advanced Search
+To use the [advanced search](https://github.com/search/advanced), Fill in the fields, and it will create your search string.
+![Alt text](_media/GitHuB_Search_Image_3.png)

docs/__gis-pantry-intro-docs__/GitHub_Web_Interface_HOW-TO.md

@@ -0,0 +1,96 @@
+***Draft: 2023-07-18***   
+***add description, tags?***
+
+# GitHub Web Interface HOW-TO
+***How to use the Github web interface to contribute to the GIS Pantry***  
+***A simple workflow***  
+.  
+***This workflow works well for simple interactions. However, more streamlined workflows are possible using [Git Hub Desktop](./GitHub_DesktopApplication.md), or [Git Hub in VS Code](./GitHub_in_VSCode.md).***  
+
+**Further Reading:**  
+*This document contains a streamlined, task-specific approach to the GitHub web interface. If you want more information about the web interface capabilities and how to use them, please see the [GitHub Documentation](https://docs.github.com/en).*  
+
+**Prerequisites**  
+This document assumes you have a GitHub account ready for use. If not please see [GitHub Account Set UP](./GitHub_Account_Set_Up.md).
+
+## Introduction
+The GitHub web interface has a lot of useful functionality. The interface allows users to manage their accounts, search for content, browse projects and documentation, track issues, and much more. 
+
+In addition to this, it also offers a handy and simple way to contribute to the Pantry for one off occasions. Once one is familiarized with the web interface it is relatively easy to use. It doesn't require set-up or configuration, users don't need to install  a desktop application, or figure out extensions in VS Code, and there is no need for the Git command line. That said, it has clear limitations, and regular coders will want to graduate to more advanced options.
+
+If you are new to GitHub it may take some time to get used to. If your are stuck then ask a colleague or search the web as needed.
+
+## Workflow Outline
+You may use the workflow below to make contributions to repositories and projects, including the GIS Pantry. 
+
+SUMMARY STEPS
+1. Fork the GIS Pantry Repo (i.e. the upstream master)
+1. Make additions / changes to your fork
+1. Sync your fork with the upstream master 
+1. Submit a Pull Request (your request to merge your changes with the upstream master)
+1. Once your request is accepted, delete Your Fork (Optional)
+1. Rinse and Repeat for Future Changes
+
+## Step-By-Step
+1. Log into your account
+1. Browse to the [GIS Pantry Repo](https://github.com/bcgov/gis-pantry)
+1. Fork the Repo
+
+    ![gif](_media/GitHub-WI_contribute_fork-repo.gif)
+
+    *Notes:*
+    - As shown above, you only need to include the master branch in your fork.
+
+1. Make your additions / changes as follows...
+    1. Edit files within the web interface (very limited, but sometimes useful for small changes.)
+
+        OR
+
+    1. Upload content you already have
+
+        OR
+
+    1. Modify content in the pantry via download + edit + re-upload with the following procedure:
+        1. Download the content
+        1. Work on it locally
+        1. Upload / Replace the content  
+            - *Notes:*
+                - This works well when you want to make a lot of changes, and need to take advantage of the software on your computer to do so.
+
+    **Examples**
+
+    - Here we edit a file directly within GitHub
+        - Click on the file
+        - Click the "code" button
+        - Click the pencil icon to edit
+        - Make your edits to the code
+        - Click "Commit Changes" (add notes if desired)
+    ![gif](_media/GitHub-WI_contribute_edit-in-web.gif)
+
+    - Here we download content to edit it locally. Later, we can re-upload.
+        - Download a Single File
+        ![gif](_media/GitHub-WI_contribute_download-file.gif)
+        - Download a whole Directory - Using a useful [3rd Party Tool](https://download-directory.github.io/)
+        ![gif](_media/GitHub-WI_contribute_download-directory.gif)
+
+    - Here we upload an entire directory via drag and drop.
+    *You can also do individual files of course, but a directory can shortcut the process.*
+    ![gif](_media/GitHub-WI_contribute_upload-directory.gif)
+
+    *Notes:*  
+    - <ins>**Make sure your upload doesn't inadvertently delete or overwrite other content that may be in the same directory.**</ins> Also, if you change file names you'll need to delete the old version from GitHub before or they will remain as separate files with the old name.
+    - In other words be aware of what you are doing.
+
+1. Sync your fork (before you make a pull request).
+    - You are syncing with the upstream master (e.g. the public GIS Pantry Repo)
+        - Syncing helps reduce possible merge conflicts, because your fork will be the same as the upstream master with the exception of your changes.
+    - In the example below there is nothing to sync, but if there is you will see a message with some details...
+    ![image](_media/GitHub-WI_contribute_sync-fork.gif)
+1. Submit a Pull Request (this will merge your changes back into the main GIS-Pantry repo)
+1. Respond to communications regarding your pull request (if there are any), make changes as needed.
+1. Once your request is accepted you are Done!
+1. Delete Your Fork (Optional)
+    - *Notes:*
+        - Good practice when you are done with your edits and won't be contributing for some time.
+        - You can easily create another fork later.
+1. **<ins>Rinse and Repeat for Future Changes!</ins>**