From 614afbbb7a4bb049e6f5536191d275d522633871 Mon Sep 17 00:00:00 2001
From: Laura M <124643236+ljmoody@users.noreply.github.com>
Date: Fri, 15 Nov 2024 12:08:32 -0700
Subject: [PATCH] Update 2.0_use_and_contribute_to_teampsd_manual.md
Added further information about pull requests and the ActionChecker.
---
2.0_use_and_contribute_to_teampsd_manual.md | 153 ++++++++++++++------
1 file changed, 107 insertions(+), 46 deletions(-)
diff --git a/2.0_use_and_contribute_to_teampsd_manual.md b/2.0_use_and_contribute_to_teampsd_manual.md
index 9a16542ac..b4ffa1751 100644
--- a/2.0_use_and_contribute_to_teampsd_manual.md
+++ b/2.0_use_and_contribute_to_teampsd_manual.md
@@ -1,8 +1,6 @@
# Use and Contribute to this Manual
-## TEST
-
-## Click Table of Contents
+## Click the Table of Contents
The Team PSD Manual's table of contents is clickable and separates into 3 header styles:
@@ -58,72 +56,135 @@ The chapters where the key term was found in will appear in the Table of Content
+## Contribute to the Manual using GitHub
-## Contribute to Manual using GitHub
-
-### 1. Create a Feature branch from the GH-Pages Branch.
+### Create a Feature Branch from the GH-Pages Branch
-- Start by creating a feature branch with the beginning of the branch named "feature-gh-pages".
+- Start by creating a feature branch with the beginning of the branch named "**feature-gh-pages**".
+- Name your branch according to the content you're revising or adding—for context and so it's easily identifiable.
- Example: feature-gh-pages_chapter_11
+ - **Note:** It is important your branch name starts with the **exact syntax** as shown above! This naming structure evokes the relevant linter actions.
+
+
-
-
+
-### 2. Create a new markdown file into the branch.
+You can now work within the newly created branch. Select an existing markdown file to edit or create a new markdown (.md) file following the instructions below.
+
+### Create a New Markdown File
+
+**Notes:**
+- Use the naming convention: (chapter #)_(title of your chapter).md
+ - Example: 11.0_ms_teams.md
+- Use all lowercase and underscores (_) instead of spaces.
+- File name must end in ".md" to indicate a markdown file (so markdown syntax will work correctly).
+- If your chapter is long, break your markdown file into sectioned markdown files to easily find the section of the chapter you want to edit.
+ - Example: 4.3_improve_team_psd_manual.md
-
+
-- Naming convention: chapter_(chapter # here)_(title of your chapter).md
- - Example: chapter_4_teampsd_monthly_process.md
+### Edit/Format the Markdown (.md) File
-- Note: If your chapter is very long, break down your markdown file into sectioned markdown files to easily find the section of the chapter you want to edit.
- - Example: chapter_4.3_teampsd_monthly_process_week_3.md
+#### Heading Rules
-### 3. Edit/format your markdown file.
+- Header 1: Title of Chapter — syntax=`# (name of chapter)`
+- Header 2: Main Sections of the Chapter — syntax=`## (name of section)`
+- Header 3 (hidden unless Header 2 is clicked on in the manual): Sub-level for the main section — syntax=`### (name of sub-level heading)`
+- Header 4 (hidden within the content of Header 3): Use to further indicate additional sections/sub-headings within a chapter — syntax=`#### (name of further sub-level heading)`
-Heading Rules
+Examples:
-- Header 1: Title of Chapter
-- Header 2: Main Sections of the Chapter
-- Header 3 (hidden unless Header 2 is clicked on in the manual): Sub-level for the main section.
-- Header 4 (hidden within the content of Header 3): Use to further indicate additional sections/sub-headings within a chapter.
+The following shows examples of headings within the manual—first, the markup syntax for headers, then a screenshot of what these headers look like in the table of contents and the manual.
-Example:
-- Header 1: Team PSD 2.0 Monthly Process
-- Header 2: Week 3: Review User Results of MVP
-- Header 3: 4.3.1 Create Screencast Video
-- Header 4: 4.3.1.1 Instructions
+- Header 1: `# Standard Operations`
+- Header 2: `## Project Trackers`
+- Header 3: `### bug_tracker`
+- Header 4: `#### Types of Bugs`
-
-
+| Table of Contents Headings | Manual Headings |
+|:--:|:--:|
+|
|
|
-### 4. Add markdown file name in the "_bookdown.yml" file.
+### Add Markdown File Name in the "_bookdown.yml" File
-- The "bookdown.yml" prints out the manual in the order of the the markdown files listed in line 6 ```rmd_files:```.
+- The "bookdown.yml" file prints out the manual in the order of the the markdown files listed in line 6 (and beyond), always beginning with `index.Rmd`, followed by .md file names.
-- Add your markdown file name in the order of which the file should appear in the manual in line 6 within the brackets.
- - Make sure to include quotations around the file name and a comma, if needed.
+- Add your markdown file name where you want the file to appear in the manual.
+ - **Note:** Make sure to include quotations around the file name and a comma, if needed!
-
+
+
+This is a great way to check the formatting and output of your markdown file in the actual Manual before you submit a pull request.
+
+### Create a Pull Request
+
+There are several ways to create a pull request; below is one example.
+
+1. Navigate to the Pull requests tab on the top navbar in GitHub.
+2. Click the New pull request button.
+
+
+
+3. Click the ```base:``` dropdown, then select gh-pages.
+
+
+
+4. Click the ```compare:``` dropdown, and select your feature branch.
+
+
+
+5. Check that you are pulling the _feature branch_ into the _gh-pages_ head branch. You should see an "Able to merge." message.
+6. Click the Create pull request button. A pull request form will appear.
+
+
+
+7. Fill out the necessary information. Then click the Create pull request button.
-This is a great way to check the formatting and output of your markdown file in the actual Manual before you hand off the review for QA Test.
+
-### 5. Check your file against the GH Actions by making a pull request to the GH-Pages master branch.
+### Check the File against GitHub Actions
+
+Once a pull request has been made, an automatic process checks the file(s) against the repo's Linter Actions. Scroll down the pull request page to see real-time progress of the Linter Actions. The screenshot below shows Actions in progress with no issues so far in the checks:
+
+
+
+#### Linter Actions
+
+Linter Actions are automated processes that check your code for issues, errors, or style violations based on predefined rules. The linters for this repo fire automatically when a pull request is made. The purpose of these actions are to ensure code quality, maintain consistency, and catch errors early.
+
+**Note:** Linter Actions will _not_ fire if the feature branch name is does not follow the exact syntax needed (see [Create a Feature Branch from the GH-Pages Branch](#create-a-feature-branch-from-the-gh-pages-branch)).
+
+**Review Linter Results**
+
+If the Actions progress area has a red X and "All checks have failed" message (like the screenshot below), click on Details in the ActionChecker to navigate to the Spell Checker, Markdown Link Checker, and Markdown Linter for Directory Level Scan.
+
+
+
+**ActionChecker details screen:**
+
+Check for a red X by each GH Action and read the output of where errors occurred. Some errors you can address yourself, some are safely ignorable, and others may need to be addressed by the Development Team.
+
+
#### Editors
-There are several editor actions that will screen your documents for proper format, compliance with editorial rules and spelling.
+There are several editor actions that will screen your documents for proper format, compliance with editorial rules and spelling. Editors refer to tools or interfaces where you can directly edit (correct) code or files if the editor actions returned errors.
+
+- The **Spell Checker** checks for spelling errors or unknown acronyms in your commit and its associated files. This check usually passes with no errors. If the spell checker throws an error, you may need to either 1) correct a spelling mistake in your document or 2) add it to Team PSD's custom dictionary file the Spell Checker uses.
+
+> Screenshot w/callouts to be developed.
+
+- The **Markdown Link Checker** will test all the links in your document to make sure they work. **It is normal for this checker to throw errors for links within the VA domain. These can be ignored.**
+
+> Screenshot w/callouts to be developed.
+
+- The **Markdown Linter for Directory Level Scan** tests your markdown file for compliance with markdown editorial rules. For example, it checks for additional spaces after each line, proper sequence of headers, bulleted lists, and other basic editorial screenings.
+
+> Screenshot w/callouts to be developed.
-- The **Markdown Editor** tests your markdown file for compliance with markdown editorial rules. For example, it checks for additional spaces after each line, proper sequence of headers, bulleted lists, and other basic editorial screenings. Below are steps to follow to use this test.
-- The **Link Checker** will test all the links in your document to make sure they work. **Recommend running this action from inside the VA Domain, as some domain links will return an error if you test outside the domain.**
-- The **APA Editor** tests your markdown file for compliance with APA rules for the use of prepositions in titles, special characters, bulleted questions and abbreviations.
-- Procedure:
- - Assign QA Test reviewers and check for a red X by each GH Action and read the output of where errors occurred.
- - Click on "Details" in the ActionChecker Action to be navigated to the Spell Checker, Link Checker, Markdown Editor and APA Editors.
- - Once edits based on failed checks and feedback from reviewers have been implemented, merge the Feature branch into the GH-Pages branch.
+Once edits based on failed checks and feedback from reviewers have been implemented, the pull request is ready to be merged.
-
+### Publish to the Master gh-pages Branch
-### 6. Publish your Chapter to master GH-pages branch.
-Merge the Feature branch into GH-page's master branch and double check that your chapter was published at https://mtl.how/teampsd_manual
+Merge the feature branch into the gh-pages head branch and double-check that your chapterr was published at https://mtl.how/teampsd_manual.
\ No newline at end of file