-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update the README to reflect the new project
- Loading branch information
1 parent
41a52d0
commit b7fc9e9
Showing
1 changed file
with
31 additions
and
104 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,131 +1,58 @@ | ||
| # HackRU Front-End (for the deprecated sourcecode) | ||
| # HackRU Frontend | ||
|
|
||
| This is the web frontend for HackRU, made with React, Redux, and Bootstrap. The live site is [here](http://hackru.org) and the development version is [here](http://dev.hackru.org) | ||
|
|
||
| 1. [Description](#description) | ||
| 3. [Inspiration](#inspiration) | ||
| 4. [Installation Guide](#installation) | ||
| 6. [TO-DO List](#to-do-list) | ||
| 7. [Links to Further Docs](#links-to-further-docs) | ||
| * [JS, CSS, and HTML](#js-css-and-html) | ||
| * [React](#react) | ||
| * [Redux](#redux) | ||
| * [Other Libraries](#other-libraries) | ||
| * [ECMA 6](#ecma-6) | ||
| * [Coding Style Guides and Linters](#coding-style-guides-and-linters) | ||
| * [Testing and CI](#testing-and-ci) | ||
| * [Version Control on Git](#version-control-on-git) | ||
| 8. [Don't Panic](#dont-panic) | ||
| 9. [Thanks for Making It to the End](#thanks-for-making-it-to-the-end) | ||
| The frontend is the main place for people to interact with HackRU on the web. It has our splash page, our sponsor package pages, the hacker dashboard, the admin dashboard (planned) and the sponsor dashboard (planned). | ||
|
|
||
| This readme is largely aimed at new developers on the frontend team. If that's you, welcome! Always remember that a README and even the extended wiki aren't fully comprehensive, so don't be afraid to ask questions in the HackRU internal chats. | ||
|
|
||
| ## Description | ||
| ## Brief Outline | ||
|
|
||
| Welcome to HackRU's front-end. The front-end is in charge of several things, namely what the user sees when accessing http://www.hackru.org, | ||
| and how the behind-the-scenes functionality operates so that people can navigate through and use the dashboard. | ||
| At a glance, don't be worried if you don't know something! We have a collection of [some resources](https://github.com/HackRU/frontend/wiki/Resources) to learn everything mentioned here. | ||
|
|
||
| Some things we do on the dashboard are: | ||
| 1. Sign up, login, and register | ||
| 2. Handle magic URL's | ||
| 3. Events list | ||
| 4. Slack messaging | ||
| 5. Admin dashboard | ||
| - The site is a [single-page application (SPA)](https://en.wikipedia.org/wiki/Single-page_application) which means that the browser doesn't have to reload the whole page when users navigate around the site. | ||
| - We use [React](https://reactjs.org) as our web framework, with [Bootstrap](https://getbootstrap.com/) as a base for our styling | ||
| - Our workflows are all based around npm and git: those are pretty much the only tools you need to know | ||
|
|
||
| There are plans to separate the dashboard into a user section (remaining on the dashboard page) and a user-agnostic section (on a "live" page, that would have events list and Slack.) | ||
| TODO: create wiki pages with resources for learning web development in general, React, npm, and git | ||
|
|
||
| ## Inspiration | ||
| ## Getting Started | ||
|
|
||
| Heman has written a nice [wiki](https://github.com/HackRU/lcs/wiki/History) discussing the history of HackRU, which is encouraged reading. | ||
| To get started with installing the repo, you should [install a recent verison of npm and node.js](https://nodejs.org/en/). NPM is what we use to install and manage the dependencies for the frontend repository. Make sure it's installed correctly with `npm -v`. | ||
|
|
||
| The people who worked on the React to its current state, AFAIK, are: | ||
| Next clone the frontend git repository somewhere on your computer, and navigate to it with a terminal session. Use the command `npm install` to pull down the resources needed to build and run the project. Once this completes, you're off to the races: use `npm run start` to launch the development web server. It should give you a link to open in your browser, where you should see your development copy of the HackRU website! | ||
|
|
||
| * Heman Gandhi | ||
| * Kabir Kuriyan | ||
| * Fan Liu | ||
| * Ryan Goldstein | ||
| If any of the steps above have an error, **please ask for help!** We're always ready to help out, and an error probably means the next step is going to wrong in a bizarre fashion. | ||
|
|
||
| The people who have worked on the CSS to its current state, AFAIK, are: | ||
| You might want to install the React Developer Tools as a browser extension. It's not mandatory but pretty helpful, for [Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/react-devtools/). It augments your existing browser dev-tools (bound to F12) with React awareness, so you can see a tree of the React components on the page. | ||
|
|
||
| * David Chen | ||
| * Kabir Kuriyan | ||
| Once you have the page running in your browser, you're all set up! Ping someone for a starter task, and embark on your HackRU adventure. | ||
|
|
||
| ## Installation Guide | ||
| ## Making a Change | ||
|
|
||
| **Make sure you read the** [handbook!](https://github.com/HackRU/handbook/blob/master/architects.md) | ||
| Once you've gotten the repository up and running, it's time to do some development. You can use any text editor with the frontend, and don't worry about code style. We have automated tools to take care of that! | ||
|
|
||
| *If you're a dev, make sure you read the* [contribution guidelines](./CONTRIBUTING.md) and the [Redux walkthrough](./ROAD_TO_REDUX.md) | ||
| The first step in your change is to create a git branch on your local repository with some relevant name. Let's say you're fixing the styling on the dashboard buttons; a good branch name would be `fix-dashboard-button-style`. Feel free to make lots of small commits during your work. The commit history within a specific change doesn't really matter: each Pull Request gets squashed down to a single commit before being merged into master. | ||
|
|
||
| 1. After cloning in and [setting up a feature branch](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow), get `nvm` in your computer. Use something like `curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash`. Don't forget to source your `.bashrc` afterwards (`source ~/.bashrc`) | ||
| 2. `nvm install 10` to get the stable release of Node. Double check with `node -v`. Then install all the dependencies listed in `package.json` using `npm install`. You should also have `aws` installed; Please only use `sudo pip install awscli`; | ||
| 3. There are two files that have authentication secrets: `.env` and `config_resume.js`. They are purposely listed in the `.gitignore`, and you'll have to acquire them separately (ask the lead of the web-frontend team). Place `.env` in the project root and `config_resume.js` in the `src` folder. | ||
| 4. Check things out by starting the server: `npm start`. Someone will probably tell you the test login/pw combo in person. Don't share it with people outside of RND. | ||
| The next step is to make edits to the relevant components, until everything works the way you want it. Again, *feel free* to ask for help throughout here. What takes you two days to figure out might take a more experienced team member all of five minutes! | ||
|
|
||
| ## Links to Further Docs (some shit I read when starting out) | ||
| Once your changes are made, it's time for some automated checks. Our checks are `npm run check`, which just reports errors, and `npm run fix`, which fixes them for you. They both invoke `prettier` and `eslint`, which are tools we use to maintain code quality. [`prettier`](https://prettier.io/) automatically formats code; [eslint](https://eslint.org/) checks it for errors or bad practice. Between the two, we try to take as much load off your shoulders as possible. Don't dedicate any thought to code styling, because `prettier` will make sure your code looks standard. `eslint` can catch some kinds of errors, like a typo in a variable name, and warn about common mistakes. *Always* commit your code before running `npm run fix`: it changes the files on disk, and if you want to undo a change, it's better to be able to take advantage of git. | ||
|
|
||
| *I will be updating this section anytime I find something useful*, so think of this less as a "required reading list" and more of a "resource reference." | ||
| But please **do read** the docs on [contributing to this project](./CONTRIBUTING.md) and [on our transition to Redux](./ROAD_TO_REDUX.md). | ||
| If you don't read those, you may easily run into issues. | ||
| The next step is to submit your code for review and CI (automated code checking). Make a pull request on the Github page, with a description of your changes. If your changes are forward-facing, include a screenshot to show them off quickly to reviewers. Once you have an approving review and the automated code checks pass (using `npm run check` from above), you can merge your code into the master branch! | ||
|
|
||
| ### JS, CSS, and HTML | ||
| (Personally I recommend W3Schools over MDN): | ||
| - [W3Schools HTML5](https://www.w3schools.com/Html/default.asp) | ||
| - [W3Schools JS](https://www.w3schools.com/js/default.asp) | ||
| - [W3Schools CSS](https://www.w3schools.com/css/default.asp) | ||
| - [MDN Docs HTML5](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5) | ||
| - [MDN Docs JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference) | ||
| - [MDN Docs CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) | ||
| TODO: write a wiki that goes into more depth about each step between making the change it showing up in the site | ||
|
|
||
| ### React: | ||
| - [React Main Concepts](https://reactjs.org/docs/hello-world.html) | ||
| - [A Really Crappy React Tutorial](https://reactjs.org/tutorial/tutorial.html) | ||
| - [A Much Better React Tutorial](https://tylermcginnis.com/reactjs-tutorial-a-comprehensive-guide-to-building-apps-with-react/) | ||
| - [A Guide to React Component Lifecycles](https://medium.com/@baphemot/understanding-reactjs-component-life-cycle-823a640b3e8d) | ||
| - [Another Guide to React Component Lifecycles](https://hackernoon.com/reactjs-component-lifecycle-methods-a-deep-dive-38275d9d13c0) | ||
| - [React Developer Tools](https://github.com/facebook/react-devtools) | ||
| - [Validating Using PropTypes](https://steemit.com/utopian-io/@jfuenmayor96/validating-the-props-of-your-react-components-with-proptypes) | ||
| ## Don't Panic! | ||
|
|
||
| ### Redux: | ||
| - [Pretty Okay Redux Documentation](https://redux.js.org/) | ||
| - [Redux To-Do List Example](https://redux.js.org/basics/example-todo-list) | ||
| - [A Really Great Read on Learning Redux](https://daveceddia.com/how-does-redux-work/) | ||
| - [Why Use Redux](https://hackernoon.com/how-to-redux-with-react-836ed6d85330) | ||
| - [Redux Developer Tools](https://github.com/zalmoxisus/redux-devtools-extension) | ||
| - [Good Example of Making API Calls in Redux](https://stackoverflow.com/questions/39813984/how-to-fetch-data-through-api-in-redux) | ||
| - [Why Use Action Creators?](https://blog.isquaredsoftware.com/2016/10/idiomatic-redux-why-use-action-creators/?utm_source=hashnode.com) | ||
| A quote from Ez, a previous frontend team lead: | ||
|
|
||
| ### Other Libraries: | ||
| - [An Overview of NPM, Babel, and Webpack](https://medium.com/front-end-hacking/what-are-npm-yarn-babel-and-webpack-and-how-to-properly-use-them-d835a758f987) | ||
|
|
||
| ### ECMA 6: | ||
| - [The Difference Between JS and ECMAScript](https://medium.freecodecamp.org/whats-the-difference-between-javascript-and-ecmascript-cba48c73a2b5) | ||
| - [ECMA 6 Features](http://es6-features.org) | ||
|
|
||
| ### Coding Style Guides and Linters: | ||
| - [Overview of Style Guides + Some Examples](https://codeburst.io/5-javascript-style-guides-including-airbnb-github-google-88cbc6b2b7aa) | ||
| - [Using ESLint](https://eslint.org/docs/user-guide/getting-started) | ||
|
|
||
| ### Testing and CI: | ||
| - [Continuous Integration Essentials](https://codeship.com/continuous-integration-essentials) | ||
| - [Getting Started with Jest](https://jestjs.io/docs/en/getting-started) | ||
|
|
||
| ### Version Control on Git: | ||
| - [Git Cheat Sheet](https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet) | ||
|
|
||
|
|
||
| ## Don't Panic | ||
|
|
||
| Seriously, this project is not part of your required curricula. It's something extra, it's something for the community, and it means learning a lot of things on the fly. | ||
| This can be a huge boon - you will definitely have a tremendous amount of experience, both technical-wise and organization-wise. This community is a great opportunity to expand your network. | ||
| "Seriously, this project is not part of your required curricula. It's something extra, it's something for the community, and it means learning a lot of things on the fly. This can be a huge boon - you will definitely have a tremendous amount of experience, both technical-wise and organization-wise. This community is a great opportunity to expand your network. | ||
|
|
||
| In case something goes wrong, or in case of a fire, or in case you feel overwhelmed or daunted by what's going on, here are some rules of thumb: | ||
|
|
||
| 1. Take some time to calm down and chill out. Health comes first, even from a practical perspective. You can't fix anything while panicking. HALT is a real good pattern to keep in mind: Don't try to work on things when you are hungry, angry/upset, lonely/lost, or tired to the extent that you can't perform properly. It will make things worse. Heroes be damned, don't try to stay up til 5am working on something on your own. If last minute crunching is needed, we shouldn't be doing it by ourselves. | ||
| 2. Write down what exactly has gone wrong and tell someone. Contact the team lead, one of the directors, our assigned rnd mentor, the git-help channel, etc. We will all will be willing to help clean up the mess. It's not just because this project affects all of us, and it's not just because we have a responsibility - it's because we literally have set shit on fire before and caused holy hell to occur through our mistakes. We want to be do as much as we can, and yelling and accusing people is definitely counter-productive. | ||
| 3. Cooperate and work together with whoever's helping you to fix what happened as much as possible. Stay on the issue, learn from it, and don't add or subtract from directions to prevent further issues from rising. | ||
| 4. After it's passed, we'll all sit down and discuss the reason for what happened. Huge breaks and long error logs can be the result of innocent mistakes or even non-mistakes that have been handled a specific way by the library/framework/language in use. We will all benefit from learning what happened and from implementing a procedure to prevent it from happening again. A good principle is to review the documentation given and to also write some of your own. | ||
| 5. Remember that communication is key, and that we are all very appreciative of your efforts and contributions. If you need to stop working on HackRU, we will understand and adapt as necessary. We just ask that you be courteous and tell of us any and all issues/questions that you have. | ||
|
|
||
| ## Thanks for Making It to the End | ||
| 1. Take some time to calm down and chill out. Health comes first, even from a practical perspective. You can't fix anything while panicking. HALT is a real good pattern to keep in mind: Don't try to work on things when you are hungry, angry/upset, lonely/lost, or tired to the extent that you can't perform properly. It will make things worse. Heroes be damned, don't try to stay up til 5am working on something on your own. If last minute crunching is needed, we shouldn't be doing it by ourselves. | ||
| 2. Write down what exactly has gone wrong and tell someone. Contact the team lead, one of the directors, our assigned rnd mentor, the git-help channel, etc. We will all will be willing to help clean up the mess. It's not just because this project affects all of us, and it's not just because we have a responsibility - it's because we literally have set shit on fire before and caused holy hell to occur through our mistakes. We want to be do as much as we can, and yelling and accusing people is definitely counter-productive. | ||
| 3. Cooperate and work together with whoever's helping you to fix what happened as much as possible. Stay on the issue, learn from it, and don't add or subtract from directions to prevent further issues from rising. | ||
| 4. After it's passed, we'll all sit down and discuss the reason for what happened. Huge breaks and long error logs can be the result of innocent mistakes or even non-mistakes that have been handled a specific way by the library/framework/language in use. We will all benefit from learning what happened and from implementing a procedure to prevent it from happening again. A good principle is to review the documentation given and to also write some of your own. | ||
| 5. Remember that communication is key, and that we are all very appreciative of your efforts and contributions. If you need to stop working on HackRU, we will understand and adapt as necessary. We just ask that you be courteous and tell of us any and all issues/questions that you have." | ||
|
|
||
| Kind regards, the web frontend team | ||
| The web team has cooled off a bit in the time since (less taking-down-production or critical bugs) but this is still very important. HackRU should not come before school, or work if it's applicable. It's ok for this not to be your first, second, third, whatever priority. The most important thing is communication: don't over-commit on what you can do, but also don't reach out to ask for help. | ||
|
|