From 8f2c90df2bb2d6c6ce29a1a52c5387cb0173ca07 Mon Sep 17 00:00:00 2001 From: Nathaniel Kim Date: Tue, 3 Oct 2023 14:40:12 -0400 Subject: [PATCH] Update docs enough for new dev onboarding (#649) --- README.md | 17 +---- backend/docs/operations.md | 10 +++ docs-general/workflow.md | 98 +++++++++++++++++++++++++ frontend/README.md | 22 +----- frontend/docs/deploy.md | 5 -- frontend/docs/local-setup.md | 33 --------- frontend/docs/workflow.md | 67 ----------------- frontend2/README.md | 55 +------------- frontend2/docs/create-react-app.md | 54 ++++++++++++++ frontend2/docs/local-setup.md | 25 +++++++ {frontend => frontend2}/docs/onboard.md | 81 ++++++++++---------- 11 files changed, 238 insertions(+), 229 deletions(-) create mode 100644 docs-general/workflow.md delete mode 100644 frontend/docs/deploy.md delete mode 100644 frontend/docs/local-setup.md delete mode 100644 frontend/docs/workflow.md create mode 100644 frontend2/docs/create-react-app.md create mode 100644 frontend2/docs/local-setup.md rename {frontend => frontend2}/docs/onboard.md (52%) diff --git a/README.md b/README.md index 1ad13688a..4986b89d1 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Galaxy is the framework that powers the infrastructure for MIT Battlecode. The galaxy consists of three main parts: -- Siarnaq, the competitor dashboard that interfaces with our data storage. +- Siarnaq, the competitor dashboard that interfaces with our data storage. (Siarnaq, in turn, has two parts: a frontend and a backend.) - Saturn, the compute cluster that compiles competitor bots and runs matches. - Titan, the malware scanner that scans all file uploads. @@ -25,17 +25,6 @@ If the Conda specifications are updated upstream, you can refresh your local env ## Development workflow -For specific development workflows in each module, see the README files in the respective folder. - -Develop new features on branches and use pull-requests to request code-review. -The `main` branch is protected and pushes to `main` will be rejected. - -We will be using the [Projects](https://github.com/battlecode/galaxy/projects?type=classic) feature to track our todo list. -Entries in the "To do" column are allowed to simply be items created in the project board, but once the entry moves to one of the other columns (e.g. "In progress"), please convert the entry into an issue for easier discussion and reference in PRs. +See [docs-general/workflow.md](docs-general/workflow.md) for workflow information. **Reading this page, especially the "Coding" and "Review" sections, before starting work is highly recommended.** -To start a feature, _claim_ it on the Projects page by moving it to the "In Progress" column and adding your name to it. Then you can work on it on a git branch. - -In places where it makes sense, it could be good to write test cases, although a lot of the functionality might not be very testable. - -GitHub has been configured to automatically verify all Pre-commit checks and in the future will also run all test cases. -It's not required to make sure every commit on GitHub passes, but anything merged to main should pass. GitHub will send you an email if the checks fail. +For specific development workflows in each module, see the README files in the respective folder. diff --git a/backend/docs/operations.md b/backend/docs/operations.md index 9ad242616..3c75f737e 100644 --- a/backend/docs/operations.md +++ b/backend/docs/operations.md @@ -1,5 +1,15 @@ # Operations +## Get dev permissions + +TODO, tracked in #681 + +## Add a dev to any team + +TODO, tracked in #681 + +This enables lots of cool technical support things. Most notably, **this is the (currently) "unofficial-official" way to view and download a team's submissions and replays**, which is helpful in debugging. + ## Resetting people's passwords Sometimes, password resets don't go through, since users never get the emails, due to issues with our email backend. No email backend will ever be failproof, so here are some other methods: diff --git a/docs-general/workflow.md b/docs-general/workflow.md new file mode 100644 index 000000000..14a3485f2 --- /dev/null +++ b/docs-general/workflow.md @@ -0,0 +1,98 @@ +# Development Workflow + +**(Disclaimer: This was written according to Nathan's philosophy. Everyone might differ! Follow what your team lead suggests.)** Feel free to adjust as you see fit, especially given the ebbs and flows of workload and resources. + +**_TLDR: students are hosed, and webinfra work can be difficult, hard to learn, or boring, especially over IAP. Do whatever you can to make this more manageable! For example, work over the year so you don't have to put out fires during IAP, and carefully prioritize work to do more important stuff first so you don't get burnt out when it comes time to do important things._** + +## High-level Goals + +The highest, most fundamental goal behind Battlecode's webinfra development: **A competition should be easy to administer.** + +This is a consequence of how Battlecode runs as a competition and as a team. In short, Battlecode development can be understaffed yet still need spiky labor, a dangerous combination that's important to mitigate. + +As a competition, user activity occurs mostly during January, and within that, mostly during specific moments or days in January. Similarly, the website's contents need to be changed during specific moments in January, such as when the game is released or tournaments occur. All of this requires large efforts from devs during small amounts of times. So, it's important to mitigate this, by reducing the amount of steps needed to run a competition and by making each of these steps easier and smaller. + +Furthermore, the Battlecode webinfra team tends to have more trouble getting hands. Devs, new and veteran, tend to be more excited by the prospect of doing engine or client work, since that's the core product of Battlecode. This makes it even harder to gather time and effort to work on webinfra. (Also, webdev is a more specialized coding framework and skill, that beginners don't tend to have, as opposed to the generic coding knowledge that engine or client may require.) + +Compounding this, the webinfra team must allot their efforts to frontend, backend, infra, deploy / release engineering, and much more. + +## Coding Principles + +Write **well-written code**. In particular, prefer code that's **ETU**, SFB, and RFC (thanks 6.031!). Especially here, _simplicity is good_, especially given lack of working resources. + +From that, modularity is also good, since this makes code much more easy to reason with and understand. This modularity can be found in many pairs of components: between back and frontend, _and between each part of frontend (e.g. between api and other things_), and finally within the same component too. + +Another practice that keep things simple is only deriving/manipulating each piece of data in one place, and then passing it down as-is in other places, as much as possible. This especially helps you reason with data being communicated back and forth. + +(While code that is performant or cool has its merits, such merits aren't as valuable in the fast-moving development of Battlecode.) + +## Things To Do + +### Organizing + +Todos are tracked in two different places: on our internal Roadmap, and on GitHub's Issues list. + +#### Roadmap + +This is our more short-term solution, which is a Google Sheet that contains a list. These todos are usually short-term ones, for parts of the codebase that are not complete and actively in development. The roadmap also tracks who's doing the todo, how long it might take, links to relevant GitHub issues and PRs, etc. + +After building out those parts, we tend to either put those todos both on the roadmap and on the issues list, or just only on the issues list (and not the roadmap at all). + +You can find it here: https://docs.google.com/spreadsheets/d/172-JYNYRjMLcSE4diH5JcxV9_2i2Q9-YzzRpktx__WE/edit#gid=1866108322 + +#### Issues + +We tend to use GitHub's issues during times of normal development. In particular, when a todo is more concrete and less obviously immediate, we turn it into an issue on GitHub. This list is used more as a backlog, and when development of all-new things slows, we tend to use this more. + +We try to assign each issue a priority, between `critical`, `medium`, and `low`. (The exact meaning of each priority has changed, as the team features different members with different work styles, and as we find a system that works the best for all of us. A rule of thumb is that if `critical` issues are not fixed before the Battlecode season, then the competition will not fully run smoothly or as promised to competitors.) + +Each issue also can belong to one or more modules (e.g. `backend`, `frontend`), and can have one or more types (e.g. `bug`, `refactor`). These, as well as priority, are assigned to issues via GitHub's labels. This allows for quick visualization and easy filtering. + +(The counterexample to this is when Dependabot makes its own PRs and issues, and gives them its own labels. In the future, we might customize these labels to better fit our needs. See https://github.com/battlecode/galaxy/issues/676 for tracking.) + +We occasionally categorize issues via GitHub's Milestones. A milestone is a collection of issues and PRs; each item can only belong to at most one milestone. Milestones are great for coordinating large projects with deadlines, such as launch date or tournaments. (Note that because each issue can only be assigned to one milestone, you must be careful to make milestones functionally distinct enough.) + + + + +### Creating + +When any task makes itself known (by your testing, other reports, code flaws, or however else): + +- Record this task somewhere! + + - If the todo is fitting for the roadmap, especially if it is to be actively worked on soon, then add it to the roadmap. + - If you use a GitHub Issue, then (if you can) give it the corresponding labels. + - (If you're having trouble deciding, then put it at least _somewhere_, or even in both. Ask the team for opinions too.) + +- Please do **not leave "TODO" in completed code. Instead, create an issue, and leave a comment referencing that issue**. It's easy to write TODOs in the code and then forget about them or never see them. A GitHub issue provides more visibility, and more safety and convenience in tracking. + (This practice also then lets you succinctly use "TODO" in your code as "within this PR".) + +### Selecting + +Now, say you're trying to do some work, and you look at the Roadmap or Issues list to pick a task to do. Before you begin a task, make a decision on whether you want to -- or should -- do this task. + +For any task, **consider the benefits of doing it**. You can think of benefits from the "negative" viewpoint too. For example, you could consider the negatives of _not_ doing it, such as the impact of security holes and breaking bugs, or the dev time inevitably lost. (Automation and refactors can be subtle, since they have little tangible impact to competitors, but they do have high benefits (and high opportunity costs!) for devs.) + +**On the other hand, consider the costs.** Remember that **your product takes effort, both to create and then to maintain.** Even if this task is easy to do in the short run, someone (perhaps not you) will have to be in charge of maintaining the finished product in the long run. + +### Coding + +Develop new features on branches. This is, in fact, almost mandatory -- the `main` branch is protected and pushes to `main` will be rejected. + +In places where it makes sense, it could be good to write automatic test cases, although a lot of the functionality might not be very testable. + +### Review + +When your code is ready, create a pull request (PR), and then request code review. All PRs require at least one person's approval to be merged to `main`. + +(If not ready but you would still like a PR, then you can create a draft PR. Press the corresponding button on GitHub.) + +Once you have a PR, then on every push, GitHub will take the latest commit and run all checks and test cases. +It's not required to make sure every commit on GitHub passes, but anything merged to `main` is required (by GitHub) pass. GitHub will send you an automatic email if the checks fail. + +## Doing Things: Working / Workstyle Preferences + +A rule of thumb: **If you're not making forward progress for a while, ask for help, or consider trying a different direction or just not achieving the thing**. While there is benefit in self-discovery, the benefits of productivity are generally worth it, especially with the limited time and unlimited backlog of student life. Also, not every features is required or mandated to do. + +Don't merge terrible-quality work -- the long-term cost of maintaining that makes it generally not worth it. Mandatory PR review ought to help this. diff --git a/frontend/README.md b/frontend/README.md index d9a84db6e..9fea0a9e7 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,23 +1,5 @@ -# Battlecode Frontend +# Legacy Battlecode Frontend Fully static frontend in React, based on `battlecode19/app`, using modified template from http://creative-tim.com. -**I would strongly recommend -- if not mandate -- that you read over this page, in full, before doing any frontend work.** - -![](screenshot.png) - -## Development Workflow - -See [docs/workflow.md](docs/workflow.md) for an idea of how to do work as part of the frontend team. **Read this page entirely before proceeding with work!** - -## Local Setup Instructions - -See [docs/local-setup.md](docs/local-setup.md) to set up a working frontend on your machine for development, or if you have issues in that setup. - -## Codebase Intro - -See [docs/onboard.md](docs/onboard.md) for an introduction to the frontend codebase, in order to make changes. **If you just need a working knowledge of frontend features / development / etc, start here!** (for example, if you're a backend dev but need to know some desired features for frontend) - -## Deployment - -See [docs/deploy.md](docs/deploy.md) to learn how to deploy changes. +**This folder (and its frontend as a whole) will soon be no longer used or maintained. See #663 for tracking.** diff --git a/frontend/docs/deploy.md b/frontend/docs/deploy.md deleted file mode 100644 index 9d8078811..000000000 --- a/frontend/docs/deploy.md +++ /dev/null @@ -1,5 +0,0 @@ -# Deployment - -TODO, this is all out of date. See #10, #11, and #179 for tracking. - -Also note that much of the deployment has been configured and automated in Terraform. See the top-level `deploy` folder to watch how deployment works. If there are still manual steps or important subtleties, we'll write them in the deploy folder. diff --git a/frontend/docs/local-setup.md b/frontend/docs/local-setup.md deleted file mode 100644 index f874fc4d2..000000000 --- a/frontend/docs/local-setup.md +++ /dev/null @@ -1,33 +0,0 @@ -# Local Setup Instructions - -## One-Time Setup - -First, make sure you have **prepared your Conda environment, according to the top-level readme.** - -Then, run - -``` -npm install -``` - -## Running - -Make sure that the backend is running. (You can hook up to a deployed backend, or run it locally. Then make sure `.env.development` points to that backend.) - -In **this directory**, run: - -``` -npm run start -``` - -This automatically reloads the page on changes. - -## Misc Notes - -Might be helpful for troubleshooting, for you or posterity. - -### Node and NPM - -When installing a new Node package, always `npm install --save `, and commit `package.json` and `package-lock.json`. - -Our local processes use `npm start` and/or `npm run start`. These commands automatically use `.env.development`, and not `.env.production`. See here for more information: https://create-react-app.dev/docs/adding-custom-environment-variables/#what-other-env-files-can-be-used. diff --git a/frontend/docs/workflow.md b/frontend/docs/workflow.md deleted file mode 100644 index f749e016e..000000000 --- a/frontend/docs/workflow.md +++ /dev/null @@ -1,67 +0,0 @@ -# Development Workflow - -## High-level Goals - -The guiding principle behind Battlecode's frontend development: **A competition should be easy to administer, and the code should be easy to understand and work with.** - -To this end are several more-specific objectives, that also guide development. See here: https://github.com/battlecode/galaxy/milestones - -This is a consequence of how Battlecode runs as a competition and as a team. In short, Battlecode frontend development can be understaffed yet still need spiky labor, a dangerous combination that's important to mitigate. - -As a competition, user activity occurs mostly during January, and within that, mostly during specific moments or days in January. Similarly, the website's contents need to be changed during specific moments in January, such as when the game is released or tournaments occur. All of this requires large efforts from devs during small amounts of times. So, it's important to mitigate this, by reducing the amount of steps needed to run a competition and by making each of these steps easier. - -As a team, Battlecode has a few quirks. First, the team -- especially the webinfra team -- is small, and devs collectively have little time and bandwidth. Compounding this, the webinfra team must allot their efforts to frontend, backend, infra, deploy engineering, and much more. Finally, frontend work can simply be unexciting. Devs, new and veteran, tend to be more excited by the prospect of doing engine or client work, since that's the core product of Battlecode. This makes it even harder to gather time and effort to work on webinfra. - -## To-do Organizing - -Todos are tracked first and foremost on GitHub's Issues list. Any frontend-relevant issues should have their title include "[frontend]". Issues are either labeled with `enhancement` or `critical`. The `critical` label is for todos that will seriously impact Battlecode, for example by creating dangerous bugs, or creating work that piles on later for devs. The `enhancement` is for less-impactful todos. (A rule of thumb is that even if `enhancement` todos are not done, Battlecode will still run smoothly and will not need overly-skilled/hyperspecialized devs. This does not apply to `critical` todos of course.) - -Further, these issues can also be categorized via GitHub's Milestones. There are various milestones relating to the frontend work, and issues that cleanly match a milestone are assigned to that milestone. You can see the list of milestones from the issues list. - -To track and organize progress on the issues, we use GitHub's Projects. See here for the frontend project: https://github.com/battlecode/galaxy/projects/2. The left column lists the high-level goals and milestones, in order to make sure we're always aware of the big picture. Then, issues and PRs are sorted into high, medium, or low priority. - -## To-do Creation - -When _any_ frontend-related task makes itself known (eg by your testing, other reports, code flaws, etc): - -- Create an issue. Make sure its title includes "[frontend]". Label it with "enhancement" or "critical"; see the "To-do organizing" section and use your judgement to classify this. Finally, if applicable, add it to a relevant milestone. - -- Please do **not write "TODO" in code. Instead, create an issue, and leave a comment referencing that issue**. It's easy to write TODOs in the code and then forget about them or never see them. The Issue list is a much safer place to track them. - -- If it needs to be be actively in the team's conscience, then add it to the project board. - -## Work Decisions - -Now, say you're trying to do some work, and you look at the Issues list to pick a task to do. - -**Before you begin a task, make a decision on whether you want to -- or should -- do this task.** - -For any task, **think about the benefits of doing it**. It's especially helpful to think of how much dev time is lost to not doing it: how much extra hoops devs jump through to do simple tasks, how much time devs spend instructing users to carry out workarounds, etc. Of course, _security holes and breaking bugs_ have extreme benefit, since the cost of not doing them -- that is, having breaking bugs and security holes -- is as high as it could be. - -Sometimes tasks may not be highly beneficial. For instance, you could be making a change to a one-line piece of code that devs would not be stumbling on anyways, or simplifying a workflow that occurs once-a-year during dead time. - -**On the other hand, judge the costs.** Remember that **your product takes effort, both to create and then to maintain.** Even if this task is easy to do in the short run, someone (perhaps not you) will have to be in charge of using your product and maintaining it in the long run. The frontend team's lack of time makes this especially problematic. - -So, **consider being light on features and new code.** This is an all-new creation of code, and yet another distinct piece of technology that someone on the team will have to wrap their head around. This person will have to learn from scratch (rather than simply replacing/updating knowledge). - -**Deciding whether to do other tasks, such as automation and refactors, involves more nuance.** Sometimes, the cost of _not_ doing this task is high. For example, the cost of not having automation for a frequent or time-sensitive operation can be high, because the manual process would require high effort. And frontend devs already are strained with effort! Another example is refactoring code that is likely to be touched again later: trying to add a feature to already-bad code becomes extremely hard, so that's a high long-term cost. - -## Working / Workstyle Preferences - -A rule of thumb: **If you're not making forward progress for 10 minutes, ask for help**. This _includes making progress but nothing that's clearly in the direction of your solution_. While there is benefit in self-discovery, it might not be worth that extra time, effort, and potential frustration. Instead, the benefits of productivity are generally worth it. This especially holds for the frontend dev team and limited time. (Plus, asking for help is a useful skill, and the _habit_ to ask for help is useful too!) - -Similarly, **if you can't solve a problem after 20 minutes, think about trying a different solution or just not solving it**. While clean code and clean solutions are good, it's perhaps not worth the effort, especially with how much work among Battlecode/frontend there is to do and how little time Battlecode devs have. Perhaps the problem could take a different approach. Or perhaps you don't even need to solve _this specific problem: zoom one level out, and try something different there that avoids this problem altogether_. - -_An important caveat:_ Don't merge terrible-quality work, of course. The effort needed to learn and maintain that is tough. So, if you write hacky or unelegant solutions, at least make sure others can follow your code along. PR review ought to help this. - -Feel free to adjust those minute values as you see fit, especially given the ebbs and flows of team workload and team size/bandwidth/resources/time. The general practices still hold and would still be useful. - -## Engineering Principles - -Write **well-written code**. In particular, prefer code that's **ETU**, SFB, and RFC (thanks 6.031!). Especially here, _simplicity is good_, especially given lack of working resources. - -From that, modularity is also good, since this makes code much more easy to reason with and understand. This modularity can be found in many pairs of components: between back and frontend, _and between each part of frontend (e.g. between api and other things_), and finally within the same component too. - -Another practice that keep things simple is only deriving/manipulating each piece of data in one place, and then passing it down as-is in other places, as much as possible. This especially helps you reason with data being communicated back and forth. - -(While code that is performant or cool has its merits, such merits aren't as valuable in the fast-moving development of Battlecode) diff --git a/frontend2/README.md b/frontend2/README.md index a24cdb3d9..d06a3000e 100644 --- a/frontend2/README.md +++ b/frontend2/README.md @@ -1,54 +1,7 @@ -# Getting Started with Create React App +# Battlecode Frontend -This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). +The new and improved frontend, for the Battlecode competitor portal. -## Available Scripts +## Codebase Intro -In the project directory, you can run: - -### `npm start` - -Runs the app in the development mode.\ -Open [http://localhost:3000](http://localhost:3000) to view it in the browser. - -The page will reload if you make edits.\ -You will also see any lint errors in the console. - -### `npm test` - -Launches the test runner in the interactive watch mode.\ -See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information. - -### `npm run build` - -Builds the app for production to the `build` folder.\ -It correctly bundles React in production mode and optimizes the build for the best performance. - -The build is minified and the filenames include the hashes.\ -Your app is ready to be deployed! - -See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information. - -### `npm run lint` - -Runs ESLint and Prettier checks - -### `npm run format` - -Applies ESLint and Prettier fixes. - -### `npm run eject` - -**Note: this is a one-way operation. Once you `eject`, you can’t go back!** - -If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project. - -Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own. - -You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it. - -## Learn More - -You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started). - -To learn React, check out the [React documentation](https://reactjs.org/). +See [docs/onboard.md](docs/onboard.md) for an introduction to the frontend codebase, in order to make changes. This is helpful not only for frontend devs themselves but also for **just a working knowledge of frontend features, even if you're not a frontend dev!** diff --git a/frontend2/docs/create-react-app.md b/frontend2/docs/create-react-app.md new file mode 100644 index 000000000..a24cdb3d9 --- /dev/null +++ b/frontend2/docs/create-react-app.md @@ -0,0 +1,54 @@ +# Getting Started with Create React App + +This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). + +## Available Scripts + +In the project directory, you can run: + +### `npm start` + +Runs the app in the development mode.\ +Open [http://localhost:3000](http://localhost:3000) to view it in the browser. + +The page will reload if you make edits.\ +You will also see any lint errors in the console. + +### `npm test` + +Launches the test runner in the interactive watch mode.\ +See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information. + +### `npm run build` + +Builds the app for production to the `build` folder.\ +It correctly bundles React in production mode and optimizes the build for the best performance. + +The build is minified and the filenames include the hashes.\ +Your app is ready to be deployed! + +See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information. + +### `npm run lint` + +Runs ESLint and Prettier checks + +### `npm run format` + +Applies ESLint and Prettier fixes. + +### `npm run eject` + +**Note: this is a one-way operation. Once you `eject`, you can’t go back!** + +If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project. + +Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own. + +You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it. + +## Learn More + +You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started). + +To learn React, check out the [React documentation](https://reactjs.org/). diff --git a/frontend2/docs/local-setup.md b/frontend2/docs/local-setup.md new file mode 100644 index 000000000..e1ceaf6bb --- /dev/null +++ b/frontend2/docs/local-setup.md @@ -0,0 +1,25 @@ +# Local Setup Instructions + +## One-Time Setup + +First, make sure you have **prepared your Conda environment, according to the top-level readme.** + +Then, run + +``` +npm install +``` + +## Running + +Make sure that the backend is running. (You can hook up to a deployed backend, or run it locally. Then make sure `.env.development` points to that backend.) + +In **this directory**, run: + +``` +npm run start +``` + +This automatically reloads the page on changes. + +For more info of what you can do to set up or run the frontend, see [create-react-app.md](create-react-app.md). diff --git a/frontend/docs/onboard.md b/frontend2/docs/onboard.md similarity index 52% rename from frontend/docs/onboard.md rename to frontend2/docs/onboard.md index 5bfb5eef4..076417889 100644 --- a/frontend/docs/onboard.md +++ b/frontend2/docs/onboard.md @@ -1,35 +1,51 @@ + + # Codebase Intro and Guide +(with much help from Maggie Yao) + **If you are trying to make code changes here, make sure to read all the (sub)sections called "Technical Detail".** _If you're not trying to make code changes but just need some working knowledge, then feel free to skip over those sections._ It's helpful but not necessary. The intent of this page is to discuss technical parts just enough, to get people started or reduce confusion. Feel free to change this and add more detail as it might be helpful (although it should probably go into other pages). -## Web Programming knowledge +_(Note to editors / maintainers of this page: If you need to explain a subject, no need to reinvent the wheel! Linking to a reputable tutorial should be just fine.)_ + +## General web dev General principles and packages of web programming, that Battlecode uses. +### What is a Frontend? + +A "frontend" is, in general, the part of an application which the users interacts with. + +In the Battlecode website, on a high level, the frontend takes in URLs from the user’s address bar, and returns rendered webpages to the user. The browser's process of loading and rendering these pages involves HTTP requests to the backend server. (The backend takes in these requests, and returns information.) + +These two servers run independently of one another, and do not inherently share any information. Instead, communication is achieved through those HTTP requests. + ### NPM NPM, the Node Package Manager, is an online repository of JS packages, and a way to download and use them. It also exposes some helpful utilities. +Amazing tutorials can be found at https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/ and at https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/. I would highly recommend using them! + To run the frontend locally, you'll need to install the NPM CLI (command-line interface). See `local-setup.md` for more. -and then react-scripts +When installing a new Node package, always `npm install --save `, and commit `package.json` and `package-lock.json`. -#### Technical Detail +Our local processes use `npm start` and/or `npm run start`. These commands automatically use `.env.development`, and not `.env.production`. See here for more information: https://create-react-app.dev/docs/adding-custom-environment-variables/#what-other-env-files-can-be-used. Here's a good tutorial to NPM, that should give you all you need. (It might actually give too much detail -- feel free to strip down as necessary.) [https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/) -If this ever goes down or you don't like this tutorial, try this: [https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/](https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/) - -also, react-scripts TODO, tracked in #49 +Another useful source: [https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/](https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/) ### React React is a popular JS framework. It's great! Turning html components into variables that are manipulatable in code is great. -#### Technical Detail - If you don't have any React knowledge at all, then you should familiarize yourself with the basics. There are plenty of tutorials to get you up to speed. I enjoy React's official tutorial, here: https://reactjs.org/tutorial/tutorial.html. **In particular, make sure you read up to (and including) the Overview section**. From the tutorial, you'll want to at least familiarize yourself with: @@ -42,43 +58,37 @@ There's a couple other parts of React that we use heavily, that are not directly You may want to know how conditional rendering works -- depending on what you do, it might come up. Here's a good explanation: https://reactjs.org/docs/conditional-rendering.html -Note that as you navigate our frontend, the URL in your web browser changes. A naive website implementation would have different html files for each page. But we only have one HTML file...what gives? -This is thanks to Routes and Switches, from `react-router`. You might want to know how they work, since they might come up too. This will help you to figure out what component is being rendered, based on a URL. For explanation, you can _skim_ https://v5.reactrouter.com/web/api/Route and https://v5.reactrouter.com/web/api/Switch. If there are important details, make sure to check the docs. - -### JQuery - -#### Technical Detail - -You actually probably don't need to know how JQuery works, other than how its API is exposed as a dollar sign object. TODO good links? tracked in #49 +TODO notes about react routes, and how our code takes in URLs and determines what to actually return. Link: https://reactrouter.com/en/main/route/route. ### APIs and the Web ### HTTP Requests -What is? TODO Link to a small explanation. tracked in #49 -Note that this is a thing for backend and frontend! +What is? -#### Technical Detail + + +Note that this is a thing for backend and frontend! -TODO link to a small explanation. tracked in #49 + ### Async, Promises, and Callbacks -TODO one-sentence description if at all. tracked in #49 - -#### Technical Detail + -TODO link to a small explanation. tracked in #49 +## Battlecode-specific web dev -Any linked explanation or explnation we write ought to discuss +Here are (some) specifics about Battlecode's frontend -- about how the codebase is set up, how it works, etc. -- at a high level, what async programming is -- promises in vanilla JS first, -- and then how JQuery's AJAX works +This will be developed over time, as the new frontend is developed, too. -## Battlecode-specific frontend knowledge +