How to add puzzle to webification repo - PuzzleServer/mainpuzzleserver GitHub Wiki

1. Assuming you have the repo, create a new branch in git
   • First, make sure your command prompt is currently at the base level of the repo folder that was just created. This doesn't happen automatically after you clone, so you'll need to "cd" into it. You'll know you're at the root level if you do a "dir" command and see a file called ".gitignore".
   • Next, to make sure you're up to date with the latest changes from everybody else, type git pull. Since you just cloned, you'll already be up to date, but it's very important to do this periodically, especially before you start making big changes. This will ensure you don't need to do any work later to merge other peoples' work into yours. This is also a good way to confirm you're in the correct folder in the command prompt, since you'll get an error message like "fatal: not a git repository" if you're not.
   • At this point, or one of the future steps, git may also complain that it needs you to run a couple of git config commands. If it does, just type the commands it gives you, which are likely just setting what user and email is currently making changes.
2. To make a new branch, first make sure you're currently on the main branch. To do this, type git branch. The current branch will be starred and highlighted:
   
   
   If you're NOT on the main branch, type git checkout main, and then don't forget to pull as well. Then, to create your new branch, type git checkout -b <branch name>.

• The branch name can be anything, but it's good practice to use one branch per puzzle, and to also put your name in the branch name so people can easily find their own branches. For example, you could do git checkout -b users/joshbo/ebay for a puzzle named "ebay" and a user named "joshbo".
• Note that the branch name has nothing to do with the files inside it automatically, and it's just good practice to name your branch after the work you're doing. Git is just a system for tracking work, so if you want files inside your branch with a certain name, you have to create those files in Windows Explorer or another program.

12. Immediately push your new branch by typing git push so that the online repo is aware of it. The first time you do this, you will see an error message:
    
    
    Copy and run the exact command it gives you (git push --set-upstream origin <branch name>). You'll only need to do this once per branch you create; every other time, you can just do a regular git push. To copy text from the command prompt, highlight it, then right-click to copy what's highlighted.
13. Now, you're ready to start editing files. Please note: don't ever edit anything UNLESS you're currently in your own branch. If you want to go to another machine and check out a local copy of a branch you've already pushed, you can just do git checkout <branch name>.
14. In VS Code, click the top button in the sidebar to open the Explorer pane. It should say that no folder is opened if this is your first time doing anything:
    
    
    Click the Open Folder button and find the folder that you cloned the repo into. Don't go INTO the folder; just highlight it in the main part of the window (not the left bar, if you have a left bar with a list of folders) and click "Add":
    
    
    VS Code may ask if you trust the authors of the files, which you can say Yes to. The next time you open VS Code, it should remember where it was, but if it doesn't, make sure you always have this folder open in your workspace since it's what lets the extension you installed work properly due to the way we've set up our resources.
15. Now that you've got your list of files available in VS Code, you can just double click anything from there to open it:
    
    
    If you're creating a new puzzle, make sure you copy an example to get started with and rename the copy; don't ever make edits to existing files that aren't yours since somebody else may also be working on them!

• To make a copy of a file, you can just do that the way you usually do in Windows Explorer, and VS Code will automatically see the new files.
• If the repo has been set up using our other wiki pages, there will likely be a clearly marked "example-puzzle" folder for you to copy and rename to your puzzle's name, as well as clear instructions in the file for where to add your changes.
• The repo that contains the puzzles may also contain a README file (which is also displayed on the website for the repo) with abbreviated instructions for adding a puzzle. Otherwise, full webification instructions are available here. You'll probably want to read that page if you're not sure how exactly to turn your puzzle content into a functional webpage.

16. Once you've made some changes, you'll want to see what they look like. The extension we installed added a little button in the top right corner of VS Code to Show Preview:
    
    
    Clicking this will open up a browser window to whatever file is currently open/active. Note that this must be an HTML file. Even cooler though, you can make edits in VS Code while the preview is still open, and the preview will update automatically!

• Don't forget that you must also manually save your files; the preview will show you what you just typed even if you haven't saved, but for git to pick up the changes, they must be saved properly.
• VS Code won't make a big deal about telling you that it actually saved the files, so if you need confirmation, remember that you can always check in Windows Explorer by right-clicking and viewing the file's properties to ensure that the last time it was modified matches when you saved.

17. To see what changes git is aware of since the last time you pushed something to the server, you can type git status. It will also show a message saying that if you want to accept those changes, you need to add those changed files to the list of files to push:
    
    
    Note that this message may be different for newly-created files than for existing files that have just been edited.
18. Once you've made a sufficient amount of progress, you should push your changes to the server. Note that this DOES NOT automatically merge anything in; it will still live only in your branch. This is important for making sure you don't lose work though, especially if you do work from multiple machines.

• Assuming you've only changed your own files, you can easily add them all by just typing git add --all (note the two dashes).
• Otherwise, you can add individual files by typing git add <filename>, where the filename is the exact name (including the path) shown with git status.
• If you accidentally changed a file you didn't mean to, you can also follow the instruction in git status to restore any file.
• Once you've added the files, type git commit -m "commit message", where the commit message summarizes what you changed (the quotes are required).
• Then, do a git push. This is the standard 3-step process to sync your local changes with the server: add, commit, push.

19. Once you're done making changes, it's time to open a pull request so your changes can be merged into main. Note that this doesn't mean you CAN'T make any more changes though; pushing changes to a branch that has an open pull request will automatically add those changes to the pull request. Back on the repo website you were at in Step 5, if you're lucky, Github will recognize that you've made changes and will offer a button to open a pull request:
    
    
    Otherwise, you'll need to either switch to your branch from the dropdown:
    
    
    And then click the "Contribute" dropdown to surface the button to open a Pull Request:
    
    
    Or go to the list of all branches and click the ... menu for yours:
    
    
    
20. Once you've got an appropriate title and description, open your pull request and let the repo owner know you're ready for it to be reviewed. PLEASE DO NOT MERGE YOUR OWN PULL REQUESTS. The owner may want you to make changes first, and they will also be on the lookout for any merge conflicts, although those should be unlikely unless you're actively working on the same files as somebody else.

• At any point, you can push new changes into this branch, and the pull request will be updated automatically. If somebody requests changes, you can also resolve too.
• Once your puzzle is merged into main, don't forget to checkout main and git pull to update your own main branch! Or if you made changes to your own branch on another machine, you can git pull those changes to your local copy of the branch on any other machines too once you've checked out that branch.
• After the pull request is merged, if you want to make any future changes, you can still use your old branch, but you'll need to open a new pull request. If the changes you're making aren't related to the work you were previously doing in that branch, it would probably be better to instead create a new branch.
• You can also use git merge to merge changes from main into your branch at any time, but just beware that if you've done work in your branch after your pull request is merged, the two versions of that puzzle in the two branches will likely create a merge conflict!

As for actually making your puzzle, besides filling out the parts of the template that you need to, you can follow the webification guide that you likely came here from to learn how to do more than just copying and pasting. And if you're using PuzzleJS, don't forget to scroll down to the bottom of its online documentation to find the pages that list all the possible options you can use and ways to override the default styling.