CONTRIBUTING.md

Contributing to Vue3-WebDev-Kit

When working on tutorials and extensions in the Vue3-WebDev-Kit you will be working in a style that is typical of a contributor to an open source project. Each tutorial and each extension in the kit is given by a ticket in the issue tracker. You will solve the issue described in the ticket. These issues will have you build some artifacts as you follow along with tutorials and then extending them. You will submit your work by making a pull request for your feature branch.

Contribution Workflow

The sections below outline how you can complete the different things that you will need to do while working on the tutorials and extensions in this kit. Clicking the ▶ beside a step will expand the "Details" section, which will provide specific Git commands and other instructions that will be useful until you have used them enough to remember them. The ▷ symbol indicates that the step does not have additional details and is included for formatting purposes.

Starting a Tutorial

Use the following steps to start working on a new tutorial.

1. Log into your GitHub account.

   This link will take you to the GitHub login page, if you are not already logged in. If you are logged in it will take you to your personal GitHub page.

2. Open your codespace.

   This link will take you to a page where you can open your codespace, if it is not already open.

   When the codespace is ready the following message will appear in the terminal:

   *****************************************
   The Vue3 WebDev Kit is now ready for use.
   *****************************************

3. Synchronize your main branch with the upstream.

   Synchronizing your main branch ensures that you are beginning your new work from the most up to date version of the project.
   
   Running the commands below in the terminal in your codespace is one way to synchronize your main branch.

   git switch main
   git pull --ff-only upstream main
   git push origin main

4. Create and switch to a new feature branch.

   Running the commands below in the terminal in your codespace is one way to create and switch to a new feature branch.
   
   Note that you will want to change the branch name from t01-html-css-js when working on later tutorials.

   git switch main
   git branch t01-html-css-js
   git switch t01-html-css-js

5. Make a pull request for your feature branch.

   Even though you haven't done any work this is the right time to create the pull request that you'll use to turn in your work. Creating a pull request early lets the instructor know you are working and gives you a place to ask questions about your work.
   
   Running the commands below in the terminal in your codespace creates an empty commit so that you can create your pull request.

   git commit --allow-empty -m "Tutorial 01 - HTML/CSS"
   git push origin t01-html-css-js

   Now create a pull request for the tutorial-01 branch.

   • Be sure to check off the box for the topic that you are working on in this pull request.

   Note that several things will happen automatically to your new pull request. Each of these things models something that often happens in open source projects.

   1. A label will be added to your pull request that categorizes the types of changes that you are proposing. In the case of this kit, those labels indicate the tutorials and extensions that you are working on.
   2. Your pull request will be automatically converted to a draft pull request. This status indicates to your instructor that you are still working. Later you'll mark your pull request as "ready for review" to turn in your work.

Working on Tutorial Tasks

Use the following steps when working through a tutorial.

1. Watch or read the tutorial all the way through once.

   The idea here is to get an overall picture of what language features are being used and what functionality they provide. Don't worry about catching all of the details on this first pass.

2. Follow the tutorial step-by-step and build the artifact.

   For video tutorials, pause and rewind the video as frequently as necessary for you to follow along and add the code that is shown to your project.

3. View your work in the browser.

   When you have created an HTML page or a Vue app you can use the following steps to open it the browser.

   1. Click "PORTS" tab in in the bottom center of the VS Code window, just below the editor you have been using to modify the code.

      

   2. Point at the link in the second column titled "Forwarded Address".

   3. Click on the small globe icon that appears.

      

   4. Click the new tab named "Directory listing for /" that opened in your browser.

   5. Navigate to the page that you want to view in the directory structure (e.g. for tutorial 01 click web-projects and then first-website).

   6. Use the reload button in the browser to update your page when you have made changes.

4. Stage and commit the changes to your feature branch regularly.

   You should stage and commit the changes at each logical breaking point in the tutorial (e.g. after adding a new UI element, or after implementing a piece of functionality). You should have multiple commits for each tutorial.

   Running the commands below in the terminal are one way to stage and commit your changes.

   git status
   git stage .
   git commit -m "descriptive commit message"
   git status

   If you had a co-author or used AI in creating the content of the commit you will need to add appropriate attribution commit trailers, for example:

   git status
   git stage .
   git commit -m "-m "descriptive commit message" \
       --trailer "Assisted-by: GPT-3.3-Codex"
   git status

5. Ensure that the commit was successful.

   When making a commit, a number of checks are performed on the changes being committed. These checks ensure that the changes are properly formatted, use good style, and do not contain broken links or spelling errors.
   
   If any of the checks fail the commit will not be made.
   
   If the commit is not made, error information will be displayed in the terminal. Read the error messages that are displayed and try your commit again as described in step b.

6. Push your feature branch to your fork (i.e. your origin).

   Running the commands below in the terminal are one way to do this.

   git push origin t01-html-css-js

   Pushing your feature branch to GitHub automatically updates your pull request for the branch.

7. ▷ Repeat steps 2-6 until you have completed the tutorial.

Completing a Tutorial

1. Verify that your pull request contains the desired changes.

   Visit this page for instructions on how to view the changes in your pull request.

2. Mark your pull request as "Ready for Review."

   Because you made a pull request for your feature branch already, all that is necessary to submit your work is to mark your pull request as ready for review.

   Visit this page for instructions on how to mark a pull request as ready for review.

Pausing your Work

When you want to pause your work you should:

1. Stage and commit the changes to your feature branch regularly.

   You should stage and commit the changes at each logical breaking point in the tutorial (e.g. after adding a new UI element, or after implementing a piece of functionality). You should have multiple commits for each tutorial.

   Running the commands below in the terminal are one way to stage and commit your changes.

   git status
   git stage .
   git commit -m "descriptive commit message"
   git status

   If you had a co-author or used AI in creating the content of the commit you will need to add appropriate attribution commit trailers, for example:

   git status
   git stage .
   git commit -m "-m "descriptive commit message" \
       --trailer "Assisted-by: GPT-3.3-Codex"
   git status

2. Ensure that the commit was successful.

   When making a commit, a number of checks are performed on the changes being committed. These checks ensure that the changes are properly formatted, use good style, and do not contain broken links or spelling errors.
   
   If any of the checks fail the commit will not be made.
   
   If the commit is not made, error information will be displayed in the terminal. Read the error messages that are displayed and try your commit again as described in step b.

3. Push your feature branch to your fork (i.e. your origin).

   Running the commands below in the terminal are one way to do this.

   git push origin t01-html-css-js

   Pushing your feature branch to GitHub automatically updates your pull request for the branch.

3. Stop your codespace.

   Visit this page for instructions on how to Stop your Codespace.

Resuming your Work

When you want to restart your work you should:

1. Log into your GitHub account.

   This link will take you to the GitHub login page, if you are not already logged in. If you are logged in it will take you to your personal GitHub page.

2. Open your codespace.

   This link will take you to a page where you can open your codespace, if it is not already open.

   When the codespace is ready the following message will appear in the terminal:

   *****************************************
   The Vue3 WebDev Kit is now ready for use.
   *****************************************

Starting an Extension

Starting an extension is very similar to starting a tutorial.

1. Log into your GitHub account.

   This link will take you to the GitHub login page, if you are not already logged in. If you are logged in it will take you to your personal GitHub page.

2. Open your codespace.

   This link will take you to a page where you can open your codespace, if it is not already open.

   When the codespace is ready the following message will appear in the terminal:

   *****************************************
   The Vue3 WebDev Kit is now ready for use.
   *****************************************

3. Create and switch to a new feature branch.

   When working on an extension you will create your new feature branch not from main but from your feature branch for the tutorial.

   Running the commands below in the terminal in your codespace is one way to create and switch to a new feature branch.
   
   Note that you will want to change the branch names from t01-html-css-js and ex01-html-css when working on later extensions.

   git switch t01-html-css-js
   git branch ex01-html-css
   git switch ex-01-html-css

4. Make a pull request for your feature branch.

   Even though you haven't done any work this is the right time to create the pull request that you'll use to turn in your work. Creating a pull request early lets the instructor know you are working and gives you a place to ask questions about your work.
   
   Running the commands below in the terminal in your codespace creates an empty commit so that you can create your pull request.

   git commit --allow-empty -m "Tutorial 01 - HTML/CSS"
   git push origin t01-html-css-js

   Now create a pull request for the tutorial-01 branch.

   • Be sure to check off the box for the topic that you are working on in this pull request.

   Note that several things will happen automatically to your new pull request. Each of these things models something that often happens in open source projects.

   1. A label will be added to your pull request that categorizes the types of changes that you are proposing. In the case of this kit, those labels indicate the tutorials and extensions that you are working on.
   2. Your pull request will be automatically converted to a draft pull request. This status indicates to your instructor that you are still working. Later you'll mark your pull request as "ready for review" to turn in your work.

Working on Extension Tasks

Working on the extension tasks is very similar to working on the tutorial tasks.

1. ▷ Complete the tasks in the extension in the order they are given.

2. View your work in the browser.

   When you have created an HTML page or a Vue app you can use the following steps to open it the browser.

   1. Click "PORTS" tab in in the bottom center of the VS Code window, just below the editor you have been using to modify the code.

      

   2. Point at the link in the second column titled "Forwarded Address".

   3. Click on the small globe icon that appears.

      

   4. Click the new tab named "Directory listing for /" that opened in your browser.

   5. Navigate to the page that you want to view in the directory structure (e.g. for tutorial 01 click web-projects and then first-website).

   6. Use the reload button in the browser to update your page when you have made changes.

3. Stage and commit the changes to your feature branch regularly.

   You should stage and commit the changes at each logical breaking point in the tutorial (e.g. after adding a new UI element, or after implementing a piece of functionality). You should have multiple commits for each tutorial.

   Running the commands below in the terminal are one way to stage and commit your changes.

   git status
   git stage .
   git commit -m "descriptive commit message"
   git status

   If you had a co-author or used AI in creating the content of the commit you will need to add appropriate attribution commit trailers, for example:

   git status
   git stage .
   git commit -m "-m "descriptive commit message" \
       --trailer "Assisted-by: GPT-5.6 Luna"
   git status

4. Ensure that the commit was successful.

   When making a commit, a number of checks are performed on the changes being committed. These checks ensure that the changes are properly formatted, use good style, and do not contain broken links or spelling errors.
   
   If any of the checks fail the commit will not be made.
   
   If the commit is not made, error information will be displayed in the terminal. Read the error messages that are displayed and try your commit again as described in step b.

5. Push your feature branch to your fork (i.e. your origin).

   Running the commands below in the terminal are one way to do this.

   git push origin t01-html-css-js

   Pushing your feature branch to GitHub automatically updates your pull request for the branch.

Completing an Extension

1. Verify that your pull request contains the desired changes.

   Visit this page for instructions on how to view the changes in your pull request.

2. Mark your pull request as "Ready for Review."

   Because you made a pull request for your feature branch already, all that is necessary to submit your work is to mark your pull request as ready for review.

   Visit this page for instructions on how to mark a pull request as ready for review.