collaborative workflow
As explained in the class syllabus there are a number of different "tasks" you can create for your contributions to the class project. Creating a task begins by creating an "Issue" on the class repo.
-
Go to the Issues page on the class repo and click the "New Issue" button to create a new task for yourself. Create a title and describe what it is you plan to create in the comment area. Or, alternatively, you can respond to a "bug" or "enhancement" issue that I (or someone else in class) created stating your interest in working on that task.
-
When creating a new task, before pressing the "Submit new Issue" button, make sure to select the appropriate label from the panel on the right side. If your creating a "tool", "filter", "option" or "function" you can move onto step 3, but if you're proposing a new "meta" task you'll need to wait for my approval before getting started.I will assign the appropriate label to your task (because of the way repo permissions work, any "contributor" can create an issue, but only "maintainers" can assign labels¯\_(ツ)_/¯
If there are updates on the class repo that you want to download and include into your local version so that it stays up to date with the progress made by the rest of the class, you can...
- run
git pull upstream main, which essentially means "pull" all the most recent commits from the "main" branch of the remote repo named "upstream"
It's usually a good idea to pull updates before starting on a new task (but you can also do this any time during the process)
you can watch a video of the process here (specifically steps 1 - 4, as well as "how to create a Filter")
Assuming you've already setup your local project, the next thing is to get started working on that task locally. Make sure you're running a local server for testing your changes locally on your computer.
When working on a shared code base with other developers, it's important to agree on a shared code style. As defined on wikipedia, a "programming style, also known as code style, is a set of rules or guidelines used when writing the source code for a computer program. It is often claimed that following a particular programming style will help programmers read and understand source code conforming to the style, and help to avoid introducing errors." (wikipeida) There are lots of opinions on the Internet regarding what the best JavaScript coding style is (this article covers some of the more popular styles if you're curious). We'll be using the StandardJS coding style.
You can reference the most common rules of this style here but the easiest way to get acquainted with it is to install a StandardJS plugin for your preferred editor. These plugins will insert red-marks in your code when there's a syntax error as well as whenever you're not conforming to the style. Here's how to install the plugin...
- Open the Atom preferences by using the shortcut (Command+Comma on Mac, or Ctrl+Comma on Windows/Linux) or by navigating to it in the menu (Atom > Preferences on Mac, or Edit > Preferences on Windows/Linux) and choose the "Install" tab on the left.
- Then search for "linter-js-standard" (by ricardofbarros) and Install it (you may need to restart Atom to see it take effect)
- Click on the Extensions icon in the left tool bar (the icon which looks like a bunch of squares)
- Then search for "StandardJS" (by Standard) and install it.
-
if we choose to all use the same editor (VSCode) we can install StandardJS as a local dependency by running
npm install standard, but to avoid git conflicts it's best that only 1 of us does this and the rest of the class pull those changes. (you may need to restart VSCode to see it take effect). Alternatively... - ...you can install
standardglobally on your system,sudo npm install standard -g(you'll need to enter your system password to run this with 'sudo'), and then you'll also need to... - ...go to the Extension's settings (by clicking it's gear icon) and check the checkbox next to "Standard: Enable Globally". (you may need to restart VSCode to see it take effect)
- as your work locally, make sure to create clear
commitmessages that will make sense to your other collaborators. These should be brief, but clear. The last thing you should always do after working on your task for a while is to backup your progress to your forked repo on GitHub bypushing all the commits you made while working on your task.
When you've completed your task (in code conforming to the StandardJS coding style), and everything seems to be working just as you want it locally (without any bugs showing up in your web console) it's time to submit your contribution for review by creating a pull request.
- Navigate to the Pull Request (PR) tab on either the class repo's page or your forked repo's page. Click on the green "New pull request" button and make sure the request is going from the main branch of your fork into the main branch of the class repo. The arrow icon between the two conveys the direction of the pull request. Give the pull request a name/title that matches the name/title of the task you created in step 1.
Once the PR has been opened a page is created in the PR tab where a conversation about your contribution can take place. GitHub's PRs not only allow us to leave comments in markdown (similar to Issues), which is convenient for sharing code snippets as well as comments, but also enables you to reference lines of code from within the files being reviewed (like pull quotes). If I notice anything that needs addressing or changing before your contribution can be merged with the class repo I can start a "review" where I'll point out specific issues or requests including any bugs I find or any code which isn't conforming to the StandardJS coding style.
Once I've "merged" your PR into the class repo the assignment is considered "complete" the last thing you need to do is...
-
close the issue you created in step 1.
-
Lastly, before starting again from step 1, make sure your local repo is all up to date with any of your peers contributions by pulling any updates from the class repo,
git pull upstream main