-
Notifications
You must be signed in to change notification settings - Fork 1
Creating a PDD from the Template
We use Github pull requests to manage the review process for PDDs and keep an up-to-date history of all proposed projects. This guide will help you use git and github to submit a PDD for review. You will need git installed on your computer. It is available for windows, mac, and linux. There will be an alternate guide for users of the Git GUI available in the future. For tips on writing a PDD, refer to the template.
The first step is to clone the repository containing all of the PDDs and the template. First, open the command line (bash, powershell, terminal, etc). Navigate the the location you want the working folder to be located.
cd ~/Desktop or cd ~/usr/bin/src
The next step is to clone the repository. That can be done using the following command
git clone https://github.com/RIT-Space-Exploration/SPEX-Standard-Proposal.git
Do not download the zip file from the main page. This will copy the files, but not the git history.
Now, enter the repository folder
cd ./SPEX-Standard-Proposal
The next step is key. You need to make a new branch in the the git history. Think of it as a parallel history of the folder. We'll make changes here without disrupting any other users. When we're ready to combine our changes into the master branch. We will make a pull request.
git checkout -b new-branch-name
Make the branch name something descriptive and related to the project.
Now we have our own branch where we can change whatever we would like, without disrupting others who are working in this folder. Next copy the folder that says COPY_ME. Rename it to the project name. You can change this name up until you make the Pull Request, so don't stress if you don't have a final name yet.
Follow the template guide and edit the .tex file to contain your PDD content.
Next, use LaTEX to compile the actual PDF. It should have the same name as your .tex file.
Now, its time to use git again to save your work.
git add projectFolder
This command will tell git to start tracking changes in this folder. You can check to see if this worked by using this command.
git status
The folder and new PDD files should show up as green.
Next, is to commit these changes to the local git log. If you are using something like Github Desktop or Visual Studio Code, you will have a nice git commit interface for writing messages. You have two options to do it via the command line.
git commit -am "Message describing the project and what you did (keep it super short)"
git commit
Then use the vim interface to write a commit message. Now your files should be committed to the git log. You can check by using
git status
and if no files appear, then the commit was a success. You can double check by checking the actual git log
git log
You should see your commit at the top of the list with the message you gave it.
Now its time to share your changes to github.
git branch --set-upstream <remote-branch>
git push
If you try to push before setting the branch, git will helpfully yell at you and give you the proper command to use. Now your changes are saved to the cloud!
Go to the repository and click on Pull Requests, or just follow this link. You will see a list of currently open PRs and a button on the top right to open a new one.
Click that. Once here, Github should have two buttons at the top left: base, and compare. Base should default to master which is perfect. Click on compare and set it to your new branch. If it does not show up, refresh, and if it still does not show up, you were unsuccessful in pushing to github. Once you set both branches, you should see a helpful list of all the files you are adding. Make sure your .tex file, PDF, and any figures, images, and additional files show up here. When you click to create a Pull Request, a text box should appear that lets you add descriptive text. We have a helpful template you can fill out, which will make it easier for reviewers.
Now reviewers will be able to make comments, line by line, on your PDD. You can reply directly to these comments within github. When you need to make a change, you can edit your files locally, stage and commit them, then push them to github. The PR will be updated with the latest changes, and reviewers can comment on the newest files.
After the PDD has been thoroughly reviewed, members with merge access will be able to close your PR, adding your final copy of the PDD to the repository as a primary historical reference.