drewuniversitycs / volog Goto Github PK

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

A step by step series of examples that tell you how to get a development environment running.

 - First, ensure you have python installed as well as your preferred IDE.
 - Clone the repository onto your local machine.
 - In order to install all the backend (python) project dependencies, you need to set up a pipenv environment and use it as the interpreter for the project. Do so by running *pip install pipenv* and *pipenv install*. For more specific instructions look up how to use pipenv with your IDE.
 - In order to install the frontend (javascript) dependenices, you need to (1) ensure you have npm and webpack installed, (2) cd into frontend, (3) npm -i to install all the dependencies, (4) npm run dev to let webpack do its thing.
 - To initialize the database and run migrations, run the following custom command: manage.py vologo
 - Finally, cd into Volog and run the server using the "manage.py runserver" command.

PEP 8 applies to all python code. Read more about it here.
Below are some essential python style tips:

• CamelCase for class names, snake_case for basically everything else
  
• Keep things as obvious as possible - don't make acronyms unless you absolutely have to, write explicit variable names e.t.c.
  
• DRY (don't repeat yourself) is essential. If you need to write the same code twice, you can probably just refactor and avoid doing so.
  
• Speaking of refactoring - do it often, and carefully. Since this is a volunteer sustained project, there will always be engineers cycling through so keeping the code base accessible and clear is one of, if not the, most important parts of the development process.
  
• In relation to above, try and document any major decisions you make in the meta data files (i.e devblog.txt). The more of the development history is documented, the easier it will be for those who work on your code next.

When in doubt, refer to The Zen of Python, by Tim Peters:

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Refer to the Google HTML/CSS Style Guide.

Check out the Google JavaScript Style Guide.

Demonstrate how to deploy the website to production.

# TODO

The base workflow is as follows: Create New Branch -> Make Changes -> Commit/Push Changes to Your Local Branch -> When Done With Yor Work, Submit Pull Request and Request Review From Relevant Teammate -> Get Feedback -> Make Changes To The Branch If Necessary (Do NOT Open a New Pull Request) -> Get Merge Approval -> Merge Your Branch with Master -> Rinse and Repeat

Additionally, here are some essential tips for making your contributions professional and clear:

• When making a new branch, title it after the feature/task you are working on. Do not title branches after your name or other non-descriptive things. The goal of the title should be to communicate to your teammates what the branch is for and, hopefully, hint at the files that were changed.
• Ideally, each commit should be entirely self contained and only affect one part of the codebase. It's not the end of the world if multiple changes are a part of the same commit, but generally speaking the more the commit changes the functionality of the website, the more important it is to have it be it's own thing.
• When you are done working on your branch, open a pull request and (unless it's something tiny like a readme edit) request a teammate to review your changes and merge the branch into master.
• Do not push to master directly. The only exceptions to this are (1) README edits, (2) documentation updates and (3) typo fixes.
• As the saying goes, "measure twice, cut once". Before finalizing any contribution, always double check your work and make sure you did not break anything in the process. Some of the things you should verify are (1) does the server run, (2) do all the pages load properly and (3) does the feature you were working on function as expected. If they are available, run all the tests before submiting a pull request.

All version control is done with Git. If you are new, we recommend watching this video for a basic introduction. Additionally, this official github guide serves as a good introduction to the basics of the git workflow.

David Nesterov-Rappoport : NullDefault

Mahmoud A. Alminawi: malminawi

Déja Santana : d-daring

Perrfection Peterkin : Perrfection

• Hat tip and thanks to anyone whose code was used!