Skip to content

Commit

Permalink
Merge pull request #24 from HackRU/readme-tweaks
Browse files Browse the repository at this point in the history 
README follows format
  • Loading branch information
Qasim Abbas committed Jul 2, 2018
2 parents 8f71957 + 62f8dc5 commit 8653e08
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 77 deletions.
70 changes: 70 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Contributing

This is a guideline for anybody interesting in contributing.

You may be part of the HackRU R&D team, in which case you probably know a lot more about this project than the average open source contributor.

That said, it's nice to have stuff written down - not only for those not in the team.

## What is R&D and can I join?

R&D is the HackRU dev team and they oversee the creation of HackRU applications.

You can join if you're at Rutgers. Otherwise, feel free to contribute but we may not be
able to easily accommodate you.

## How to contribute?

There'll always be issues opened to summarise what the project is up to and the main heading. If an issue is labelled
"bug" or "security." it has priority. Otherwise it might bot be very important.

There's also a [list of TO-DOs in the README.](README#whats-next-for-lcs)
So that will give you an idea of the priorities. Feel free to open issues too, but the R&D team will have a project
lead who will chose the priorities.

## More technical stuff

Basically, you'll have to clone, branch, and set up the python to work.
```
git clone https://github.com/HackRU/lcs.git
python -m venv .
source bin/activate
pip install -r requirements.txt
git checkout -b my-feature-branch
```

So yeah... then you'll have to just code.
See [#20](#20) for more on the testing.

## Notes on PRs

The PRs, besides being automatically linted and tested (hopefully - [#20](#20)),
will also need a review. This is to give the project lead a little more control and to force changes to be a little
more open.

Desperate bug fixes may have to be reviewed faster, but in general many people tend to pay attention when there's a bug,
so the review should come quickly.

This is to force feature branches. Because feature branches are good and nice.

### Rebasing?

Yes.

Rebase master as much as reasonable.

This is to have a linear commit history.

And no merge commits, please.

See [the atlassian tutorial for more.](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase)

The only time and place it's OK to rebase is on master with a PR. Do not rebase elsewhere unless everybody you're collaborating
with knows you're rebasing and prepares for it.

Talk to us if you need help with a rebase or anything.

### Delete all your branches when you merge

Please. Let's not have loads of useless branches floating around.
118 changes: 41 additions & 77 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# HackRU-Application
# LCS

Checkout `Camelot-saved` for the working node thingy we used before (TODO: archive it).
Checkout `Camelot-saved` for the working node thingy we used before.
We are eternally grateful, Carlin.

## What is LCS?!
Expand All @@ -18,78 +18,42 @@ Lambdas.

We ran a few hackathons off it so, pretty ludicrous.

## Real-talk: the API

So, the API has a few endpoints, each unto it's own lambda.
The HTTP details and deployment facts are provided too.

| Endpoint URL | Endpoint method | Python file | Function name | Proxy integrate? | Depends on? |
| --- | --- | --- | --- | --- | --- |
| /authorize | POST | authorize.py | authorize | No | Libraries: mongo |
| /create | POST | authorize.py | create_user | No | authorize function, mongo library |
| /mlhcallback | GET | authorize.py | mlh_callback | Yes | authorize and create_user functions |
| /validate | POST | validate.py | validate | No | Mongo library |
| /update | POST | validate.py | update | No | Mongo library. There is a large helper function too |
| /qr | POST | qru.py | email2qr | Yes | Pillow. This includes a shared library that needs ubuntu to correctly install |

### The authorize endpoint

Given an unhashed password and the user's email, issues a token for the user.
This token represents that the user is logged in and can be
used to query the rest of the API on the user's behalf.

The endpoint expects the following JSON in the body of the POST:
```JSON
{
"email": "users@email.here",
"password": "user's password here."
}
```
Upon validity, the following JSON is returned:
```JSON
{
"auth": {
"token": "a mangled hash brown",
"email": "users@email.here",
"valid_until": "time for 3 hours from now"
}
}
```
On failure, expect an error string we think of as informative.

### The create endpoint

Given the JSON for a user in the post, with
at least an email and a password, creates the user.
Here is some JSON:
```JSON
{
"email": "users@email.here",
"password": "users password here",
"github": "their fancy git, if you have it",
"major": "their major, if known to you",
"short_answer": "HackRU does an application question and the answer is stored here, if known",
"shirt_size": "shirt size if known",
"first_name": "their name (optional)"
"last_name": "their last name (optional)"
"dietary_restrictions": "what they can't eat, if known.",
"special_needs": "Their special needs if known",
"date_of_birth": "yyyy-mm-dd", //optional
"school": "Which school they go to. Optional. Remember Penn State doesn't count.",
"grad_year": "yyyy", //optional
"gender": "their gender. Optional - both in and not in the liberal sense",
"registration_status": "unregistered", //<- should be the default, though you can pass this in.
"level_of_study": "What level of college they're in, what degree they want. If you know it."
}
```
This will result in
```JSON
{
"auth": {
"token": "a mangled hash brown",
"email": "users@email.here",
"valid_until": "time for 3 hours from now"
}
}
```
on success and a string we hope informs you on failure.
## Why LCS?

See the very salty rant on [the history of LCS](https://github.com/HackRU/lcs/wiki/History) for more.

Basically, because Heman didn't understand a codebase, he made one that the next generation won't understand.
He's tried very hard [to help with understanding](https://github.com/HackRU/lcs/wiki), but time will tell if it worked.

## How to Install LCS?

See [the deployment instructions](https://github.com/HackRU/lcs/wiki/Deploying) for too much information.

Basically, you set up AWS lambdas, an AWS API gateway API, and then a few third party APIs.
Oh yeah, and a DB... somewhere.

## Where is LCS Used?

Like... everywhere. The one app, the web frontend, and a few other apps use LCS to some extent.

This is the user registration backend, so is indispensable to anything that interacts with the hackers at HackRU.

## How Should LCS Code Look?

See [#20](#20) : I don't know yet.

## What's Next for LCS?

In order of decreasing priority:
1. [ ] Fix the password checking bugs. ([#12](#12), [#13](#13), [#14](#14), [#11](#11))
1. [ ] Check the read endpoint for security issues. ([#22](#22))
1. [ ] Add continuous integration, testing, and jazz. ([#20](#20))
1. [ ] Fix the slack endpoint. ([#23](#23))

Issues not referenced here are not thought of as essential and not a priority (so get to them if you have time).

## More on LCS?

[Ja, ein Wiki](https://github.com/HackRU/lcs/wiki). [How'd you like 'em apples?](https://www.youtube.com/watch?v=gcZPWkNY6x8 "Will Hunting and I are both being pricks.")

:beginner: :poop:

0 comments on commit 8653e08

Please sign in to comment.