Contribution (Development) Guide
For new Poll Buddy members, here's how to start making your first contributions:
For those who are not from RCOS and don't have editing access but still want to work on Poll Buddy, you can start by forking the repo.
To do this, just click Fork on the top right corner on the Poll Buddy GitHub page. If there is a window that asks Where should we fork PollBuddy? choose your GitHub username.
This should create a copy of the Poll Buddy repo in your own GitHub account. It should look like:
You can first follow these instructions on how to clone the Poll Buddy repo and install Docker on your computer.
On our GitHub page you can go to the Issues tab and look through the different issues listed and pick one of them to work on.
Each issue has at least one label that tells you what kind of issue it is (frontend, backend, documentation, etc.). You can filter by label so it will be easier to see the issues that deal with what you are interested in. Each issue is also a part of a milestone (October 2020, November 2020, etc.). Ideally, you should pick issues that have older milestones first as they are higher priority.
After looking through the list of issues and choosing an issue you would like to work on, go to the issue's page by clicking on the issue name. On the issue's page, click on Assignees on the sidebar and choose your GitHub username to assign yourself to this issue. Make sure that no one else is already assigned to the issue. If someone already is assigned, consider reaching out to them to work on it together, or if they have been assigned for a long time, see if they are still working on it.
To start working on your issue, make sure that you have cloned the Poll Buddy repo onto your computer.
Navigate to the Poll Buddy repository directory on your computer if you are not already there. In Git, branches allow you to make changes to the repository and test them locally without changing the code that is already in the repo.
To make a branch, type in the terminal:
git checkout -b name-of-your-branch
Another way to make branches and commits is to download GitHub Desktop. GitHub Desktop will help you make your branches and commit your changes without having to work with the terminal. To make an branch on GitHub Desktop, make sure that you're in the Poll Buddy repository. Then, at the top of the page click Current Branch and then New Branch.
You can use any Git-capable client you would like. Many people at Poll Buddy prefer GitKraken but you're welcome to use anything you'd like. Github Desktop is a good and easy starting place though.
Then you can name your branch and choose a branch to base this branch off of. Here, it is ok to choose master unless the issue you need to build off work you have done on another branch you have. In general, use the frontend or backend branch if your changes primarily target one of those areas. Then choose Create branch.
Now you can start working on your issue in any text editor. After making some changes you can commit the changes to your branch. Make sure to commit and push often (generally after something significant has happened like completing part of the issue, or if a lot of changes have been made and you don't want to wait too long) just in case anything happens to your computer.
Notepad is a good starting editor on Windows. Notepad++ is even better. For the most fully featured and capable development experience, we recommend using JetBrain's cross-platform IDEs. PHPStorm or WebStorm are the most relevant ones for Poll Buddy. Students can get these for FREE.
Most of Poll Buddy's structure should be pretty easy to understand. Follow the folder layouts and files and look at the comment within for more information. The Wiki is also a great place to learn more about how the app is set up. Feel free to ask any questions though (could be in the issue you're working on, in a group meeting, through an email to help@pollbuddy.app, etc.).
To test your changes, you can run docker-compose -f docker-compose.dev.yml up --build to run the app in development mode. This will automatically reload the app whenever you make any changes. It also exposes the database port for connecting directly and working with it. The JetBrains IDEs have this functionality built in, or you can use something like DataGrip or the mongo CLI.
If you would like, you can also run in production mode with docker-compose up --build, or docker-compose up -d --build. The first one will show logs in your terminal, and the second one will run it entirely in the background.
Once the Docker commands finish running, you can access various portions of the app as shown below:
The Frontend is available at http://localhost:7655.
The Backend is available at http://localhost:7655/api.
The Reporting interface is available at http://localhost:7655/reporting.
The Database is also available at localhost:27017 in development mode only.
You can also run docker-compose -f docker-compose.lint.yml up --build to check your code against our linting rules. These help ensure code is of high quality and neatly formatted. Errors need to be fixed. Warnings can be ignored but this is frowned upon. Occasionally you may find a rule that is not working correctly or you do not agree with. Please feel free to open an issue discussing this (or comment in the issue you're working on) if you'd like.
If you made a new file and would like to add that to the repo, and you're using the Git command-line tool, in the terminal you would type:
git add file-name
To commit your changes type:
git commit -m "Short message about changes you made here"
On GitHub Desktop it should show you the changes you made in the main window. On the lower left corner there should be a section where you can make your commit. In the text box next to your GitHub profile picture you can include your commit message (short description on what you did) and then you can click commit to branch-name.
Other Git clients use the same general concepts. JetBrains IDEs even have Git clients built in.
Publish your branch to the repo so then you can make a pull request later on. After pushing your branch you (and anyone else in the organization) will still be able to make commits. Pushing your branch now won't automatically implement your changes to the official Poll Buddy repo and code, but is part of the process of doing so.
To push the branch from your terminal, type:
git push origin name-of-your-branch
On GitHub Desktop you should see an option to Publish Branch after you commit your latest changes. You can just click this to push your branch.
When you are done working on your issue and have fully tested out that it works locally, you can make a pull request to merge your changes to the official repo.
On the GitHub repo you can click Branches and find your branch and click Open to open a pull request.
Alternatively you can go to the Pull Requests tab and click New Pull Request. For the base, you should put either frontend or backend depending on what your issue is. For compare, you choose the name of your branch that you should have already pushed to the repo. Then click Create pull request.
If you are pushing from a fork make sure that the base repository is PollBuddy/PollBuddy, The base is either frontend or backend, or occasionally master if the others are not applicable. The head repository should be YourUsername/PollBuddy and compare should be the name of the branch you are pushing.
Either way you want to make sure that the base branch that your pull request will be merged to is either frontend or backend, or occasionally master if the others are not applicable.
Now you should see a screen where you can fill out information about your pull request. Follow the instructions in the box to describe what you did, the type of issue you fixed, which issue this pull request closes, etc. Anything in <!-- ... --> is a comment that only someone editing the PR can see.
Now you have to assign at least two people to review your pull request. One of these people has to be the project manager (currently @hbh7).
Once your are done describing your pull request and assigning people to review it, you can click Create pull request.
If you are making a pull request from a fork, you might see an error that you failed all checks or that merging is blocked. In this case you don't have to worry about them, reviewers and the PM will look over your edits and if everything is fine, it will usually be merged in about a week. You can see #325 for a more detailed explanation.
After making your pull request, you can still make edits and commits to this branch. Sometimes reviewers will request changes and you can make those changes and push them without having to make another pull request. Make sure to leave a comment in the pull request that you made changes and committed them so the reviewers know. It can also be helpful to re-request the reviews.
Once the project manager and other team members think that the pull request is good and completed, it will be merged to the repo.
Now that the pull request is submitted and is being reviewed, you can go to the issues tab and pick out another issue that interests you and start working on that!