Update Practice Problem Guidelines

Added instructions on how the PR workflow works for C4T. Also changed Google Form to be only for those without GitHub accounts.

Author: phrdang

README.md

@@ -50,27 +50,54 @@ Please follow the following guidelines when creating or finding practice problem
 If you have questions, send a message to #questions on the teachers Discord.
 
 ## Follow good programming style.
+### Install Linters
+This will save you time because when you submit a pull request (PR) on GitHub, we check for good programming style. Your PR will not be approved unless it passes those style checks. Also, linters basically enforce all of the style rules that we discuss below, so you basically can just skip to the next section (Follow the C4T practice and solution problem format).
+
+* Java: Install checkstyle (SonarLint recommended as well)
+* Python: Install flake8 (pylint recommended as well)
+* HTML/CSS: Install SonarLint (recommended)
+
+This should go without saying, but actually use the linters! If you see errors/problems/warnings, address them, don’t ignore them and keep going!
+
+**Note:** We highly recommend that you use [Visual Studio Code](https://code.visualstudio.com/download), because it has a lot of useful extensions you can install with a few clicks (including the linters mentioned above). It also has great Version Control System (VCS) integration and extensions.
+
+### Whitespace
 * Indent properly.
 * Make sure there are spaces between binary operators, parentheses, curly braces, etc. when applicable. (For method/function calls, there should not be a space between the method/function name and the parentheses.)
-* Name files so that they are representative of what the program is about.
+  * For HTML, attributes should not have spaces between the attribute name, equal sign, and attribute value
+* Leave empty lines where appropriate to increase readability
+
+### Naming
+* Name files so that they are representative of what the program is about. File names are also the name of the practice problem.
   * Avoid naming files after concepts, like “Arrays.java”
+  * Java: Use class naming conventions to name files. For example, HelloWorld.java rather than helloWorld.java or hello_world.java or something else
+  * Python: Use snake case to name files. For example, hello_world.py rather than HelloWorld.py or helloWorld.py or something else
 * Name variables/methods/functions descriptively, and follow your language’s conventions.
-  * Java: camelCase for regular variables, snake case (and uppercase) for constants
-  * Python: Snake case for regular variables, snake case (and uppercase) for constants
+ * Java: camelCase for regular variables, snake case (and uppercase) for constants
+ * Python: Snake case for regular variables, snake case (and uppercase) for constants
+
+### Reduce complexity
 * If a line of code is very long, separate it into 2+ lines (e.g. for long lists/arrays, long print statements, etc.)
-* Leave whitespace where appropriate to increase readability.
-* Add comments to explain parts of your code.
+* Add comments to explain parts of your code
+* Break up the program into methods/functions if applicable and if the students have learned about methods/functions at that point in time.
 
 ## Follow the C4T practice and solution problem format.
-* All code filed under `practice` should be templates. Templates may include things like an empty class and main method. They must include a multi-line comment with the full instructions that are also displayed on Thinkific at the top of the program.
-* All code filed under `solutions` should be solutions. Solutions should include the full instructions at the top of the file and then a possible solution to the problem.
-* The practice template and solution should have *the same file name.*
-* For Java teachers: Make sure that you have the correct package statement as the first line of your code.
-
-## Thoroughly test your solution. Make sure it works as intended.
+* Make sure you put the file(s) in the right directories.
+  * All code filed under “practice” should be templates.
+    * Templates may include things like an empty class and main method.
+    * They must include a multi-line comment with the title of the practice problem AND the full instructions for the problem.
+  * All code filed under “solutions” should be solutions.
+    * Solutions should include the practice problem title AND full instructions at the top of the file (exact same comment as in the practice template file) and then a (possible) solution to the problem.
+* The practice template and solution should have the same file name.
+* Java: Make sure that you have the correct package statement as the first line of your code.
+
+## Testing
+* Thoroughly test your solution. Make sure it works as intended.
+  * Try to break your program! Don’t just give input you know will work.
 * Hundreds of students and ~50 teachers could potentially see and use your work. Please make sure that it works!
 
-## Make sure that the problem is doable for the skill level of your students.
+## Check the content.
+* Make sure that the problem is doable for the skill level of your students.
 * Check Thinkific to see if the concepts that you need to solve the problem have been covered already.
 * Be aware of how long your own class takes on other practice problems.
 * Practice problems shouldn’t take several hours/days.
@@ -81,32 +108,35 @@ If you have questions, send a message to #questions on the teachers Discord.
 * If you found it in a book, cite the full title and author.
 
 ## Submit practice problem(s).
-### Overall directions no matter which option you choose:
-* Make sure you push to the correct folder and repository.
-* Instructions should be formatted as follows:
-
-> **Practice:** [full instructions]
->
-> **Practice template:** practice/[FileName].extension
->
-> **Solution:** solutions/[FileName].extension
-
-To submit a problem, you have 3 options:
-
-### (1) Pushing to GitHub
-1. Dm Rebecca Dang on the Teachers Discord with your GitHub username and course(s) you’re teaching to be invited to the C4T GitHub organization
-2. Clone the repo.
-3. Create your own branch. Name it appropriately.
-4. Push your branch to remote.
-5. Mention @Curriculum Development on the Teachers Discord that you have pushed your branch. Be sure to tell us what the name of your branch is!
-6. If Curr-Dev approves, you have permission to merge your branch with master.
-
-### (2) Making a pull request
-[See this help article](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
-
-### (3) Email C4T Curriculum Development
-1. Email [[email protected]](mailto:[email protected]) with all necessary info (e.g. instructions, practice template file, solution file). 
-2. Mention @Curriculum Development on the Teachers Discord that you have emailed us please!
-
 
-Thank you teachers for following these guidelines and helping us build a problem base!
+### Option 1: Use GitHub
+***Note 1:** If you choose option 1, we assume you know basic Git, e.g. committing, pushing, pulling, branching, merging, etc. If you want to learn the basic Git you need to contribute, we recommend watching [this entire playlist.](https://www.youtube.com/watch?v=3RjQznt-8kE&list=PL4cUxeGkcC9goXbgTDQ0n_4TBzOO0ocPR&index=1)*
+
+***Note 2:** If you want an overview of the Pull Request (PR) workflow we are using, read these articles.*
+
+1. Send your GitHub username to a Curriculum Development member and ask them to add you as an outside collaborator on the repository or repositories that you want to contribute to.
+2. Clone or fork the official C4T repository.
+  * All repositories can be found here: https://github.com/code-for-tomorrow 
+  * [How to Clone](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository)
+  * [How to Fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
+3. Work on the practice problems locally.
+  * If you cloned the repo, make sure you create and checkout a new branch. **DO NOT MAKE EDITS ON THE MASTER BRANCH.**
+  * If you forked the repo, you’re free to work on the master branch or make your own branches (though that is kinda unnecessary).
+  * [Git Branches Tutorial](https://www.atlassian.com/git/tutorials/using-branches)
+4. Push your local branch to remote.
+  * [How to Push](https://help.github.com/en/github/using-git/pushing-commits-to-a-remote-repository)
+5. Make a pull request to merge your branch with the master branch of the official C4T repo.
+  * Make sure that the title of your pull request is descriptive but concise.
+  * In the description part of your pull request, you should specify the following:
+    * Your full name (if it’s not clear from your GitHub profile)
+    * Chapter # and section name that this problem should go under (for example, Ch. 1 Intro to Python, Section: Comments)
+  * [How to Create a Pull Request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)
+6. Mention @Curriculum Development on the Teachers Discord that you’ve submitted a PR.
+7. Monitor the status of your Pull Request on GitHub. 
+  * It’s possible that the Curriculum Development team will Request Changes, in which case you will need to commit those changes before your PR will be approved and merged into the official master branch.
+
+### Option 2: Use the Google Form
+Submit a problem [here](https://forms.gle/hDWrPRG3HuAgUdCJ9) if you don’t have a GitHub account.
+
+
+**Thank you teachers for following these guidelines and helping us build a problem base!**