Skip to content

Updated & Restructured Dev Docs, Updated Footer and Sidebar #352

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Updated & Restructured Dev Docs, Updated Footer and Sidebar #352

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d631192
Added node and yarn setup
matthewcn56 May 27, 2021
5f1966e
Separated dev setup pages
matthewcn56 Jun 15, 2021
2450673
Restructured dev docs even more, updated
matthewcn56 Jun 22, 2021
82cbdd2
Fixed sidebar formatting for static-setup
matthewcn56 Jun 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,5 @@ _site/
.jekyll-metadata
.DS_Store
.vscode
vendor/
*.*~
188 changes: 46 additions & 142 deletions _docs/dev-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,10 @@ sidebar-title: "Dev Setup"
# Dev Setup: In-Depth Walkthrough
{:.no_toc}

You want to contribute to the Teach LA Website! Awesome! Before you get started, you'll need to set up some things. Here, we'll walk you through step-by-step how to set up each component. We'll tell you how to check if you already have each component, how to briefly install it if you don't, and then show you some extra resources where you can learn more (but only if you want)!
You want to contribute as part of Teach LA's dev team! Awesome! Before you get started, you'll need to set some resources up if you want to work on the website or one of our projects. Here, we'll discuss how to use our shell, git, and GitHub!

Some of this may already be familiar for you. Feel free to skip around to the parts that are relevant.

You may ask: why is the website so complicated to set up! You may have a point, but it allows us to write features that let you update the website **without writing code**: we've written templates that generate pages, content, and complicated data relationships, so you don't have to! Hopefully, with practice, you'll find this to be not too tricky.

## Table of Contents
{:.no_toc}
* TOC
Expand Down Expand Up @@ -91,88 +89,59 @@ For OSX, the installation process will seem rather complicated, but you should e
To check to make sure that Git is working as expected, open your shell and run `git -v`. It should output something like this:

```sh
tla@acm:/my/path/to/teach-la-website$ git --version
tla@acm:/my/path/to/my-current-project$ git --version
git version 2.25.1
```

Don't worry if your prompt looks a little different. What we care about is the version output here.

After this, we are ready to get started.

## One-Time Setup
## Development Workflow

These next steps take a few minutes of time, but you *only need to do them once*.
In this section, we'll talk about how we can use the features of git and GitHub to collaborate with other people when making changes to our repositories!

### Cloning our Repository
### Cloning Repositories

Our first step is to "clone" the repository, which means grabbing a local copy of the website to make changes to. We do that with the `git` command:
Our first step to start working on changes is to "clone" a repository, which means grabbing a local copy of a website we want to make changes to. We can do that with the `git` command:

**Cloning TeachLA's Website**
```sh
$ git clone https://github.com/uclaacm/teach-la-website.git
```

What this does is grab the copy of our website located on GitHub, and creates a local copy on our computer.

Once that command is done, a new folder will have been created. We can check if it's there with the `ls` command:

**Cloning Any Project On Github**
```sh
$ ls
js-backend teach-la-website # <-- there it is!
gradient-descent-visualiser network-tarines
$ git clone https://github.com/LINK_TO_YOUR_PROJECT
```

We can then enter the directory with the `cd` command, so we can do some more things.

```sh
$ cd teach-la-website
```

And now we've installed a local copy of our website! But we're not done installing yet...

### Installing Dependencies

Our website is built with [Jekyll](https://jekyllrb.com), a "static-site generator". Really, it's a piece of software (written in Ruby) that helps us make our website. But, we have to install it first!
What this does is grab the copy of our website located on GitHub, and creates a local copy on our computer.

Almost all computers have ruby installed. To double-check, you can run the following command in your shell:
To see what link you need to input when cloning a repository, just press the code button on the top of the [repository](https://github.com/uclaacm/teach-la-website) you want to work on and copy the url that appears to your clipboard!

```sh
$ ruby -v
ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin20]
```
![Github Cloning URLs]({{ site.baseurl }}/img/docs/git-url.png)

If you don't have Ruby on your system, you can check the [appendix entry: installing ruby with rvm](#appendix-installing-ruby-with-rvm).
From here on, we'll use the teach-la-website as our example of navigating git!

First, we'll install a "helper" tool called `bundler` that lets us install libraries easily.
Once that command is done, a new folder will have been created for your project. We can check if it's there with the `ls` command:

```sh
$ gem install bundler
$ ls
js-backend teach-la-website # <-- there it is!
gradient-descent-visualiser network-tarines
```

If this command doesn't execute properly, then there's two things you can do:
1. Run `sudo gem install bundler` instead.
2. Install RVM [using our appendix entry](#appendix-installing-ruby-with-rvm) and then re-run the command.

Then, we'll run a new command, called `bundle`. It will install all of our dependencies.

*Note: this might take a few minutes, depending on your internet connection and computer.*
We can then enter the directory with the `cd` command, so we can do some more things.

```sh
$ bundle
$ cd teach-la-website
```

Great! That's it, and we're ready to start actually making changes!

One last tidbit: every now and then, we'll make changes that update our dependencies. The command line will tell you to run `bundle` again (just like we did), so you should do just that.

## Development Workflow

Okay, so how do we make changes to our site? We'll walk you through what you need to do to get your site up and running.

### Create a New Branch

We want to make sure that changes we make don't impact other people, or at least not until those changes are done. Out of courtesy, we'll develop our changes on our own "branch", which is a version of our code.

The default branch is called `master`, and it contains the code that goes live on [teachla.uclaacm.com](https://teachla.uclaacm.com). We don't want to touch that just yet, so we're going to make our own branch!
Default branches are either called `master` or `main`, and they contain the code that goes live on our websites' links! For instance, `teach-la-website`'s master branch code can be seen on [teachla.uclaacm.com](https://teachla.uclaacm.com). We don't want to touch that just yet, so we're going to make our own branch!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the future, we should shift all of our branches to main - makes writing this a lot easier.


We can check what branch we're on with the `git branch` command:

Expand All @@ -183,7 +152,7 @@ $ git branch
working-on-new-ai-ml-collection
```

The `*` means that we're currently on master. Let's make a new branch from master, with the `git checkout -b` command:
The `*` means that we're currently on master. Let's make a new branch from master/main, with the `git checkout -b` command:

```sh
$ git checkout -b my-new-feature
Expand All @@ -196,36 +165,6 @@ $ git branch

Great! Now we're ready to make our changes.

### Running Jekyll with Bundle

It turns out, we need to "compile" our website. Weird, right? Let's do it, with the `bundle exec jekyll serve` command; you'll get something like this:

```sh
$ bundle exec jekyll serve
Configuration file: /Users/matt/code/teach-la-website/_config.yml
Source: /Users/matt/code/teach-la-website
Destination: /Users/matt/code/teach-la-website/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.17 seconds.
Auto-regeneration: enabled for '/Users/matt/code/teach-la-website'
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
```

In your browser, visit what follows the "Server address" line, which is almost always [http://127.0.0.1:4000/](http://127.0.0.1:4000/). You should see a copy of your site up and running!

### Make your Changes

Now, you just need to make some changes.

Open up the `teach-la-website` folder in your favourite text editor (good free options are [Visual Studio Code](https://code.visualstudio.com/), [Sublime Text](https://www.sublimetext.com/),. or [Atom](https://atom.io/), but you can use whatever you like).

Then, poke around the files and make your changes. Not sure where to make the changes? That's where our other pages help you out!

One quick thing: every time you save a file, Jekyll is smart enough to auto-rebuild the site! So, after you make a change, refresh the site in your browser, and you should see your change reflected!

And that's it! You've made some changes!

### Add, Commit, and Push

Expand Down Expand Up @@ -292,11 +231,33 @@ And we'll do exactly what `git` tells us to do:
$ git push --set-upstream origin implement-docs-collection
```

And we're done! If you go to the [branches section of our GitHub repository](https://github.com/uclaacm/teach-la-website/branches), you should see your branch there!
And we're done! If you go to the [branches section of the GitHub repository you're working on](https://github.com/uclaacm/teach-la-website/branches), you should see your branch there!

You can keep on adding, committing, and pushing changes as you see fit.

When you are ready to merge, then you can create a **pull request** -- something we cover in [our next guide]({{ site.baseurl }}/docs/static-setup)!
When you are ready to merge, you can create a **pull request**!

### Making a Pull Request

Now that you've pushed some code to the repository, you can submit what's called a **pull request**, or a request to merge your changes on one branch into another. GitHub makes this very easy, so let's navigate to your [repository's GitHub page](https://github.com/uclaacm/teach-la-website). If we're fast enough, we'll see a notification stating that our branch was recently pushed, along with a suggestion to make a pull request from it.

Go ahead and click on "create a pull request" to proceed, and you'll be presented a form to write a title for your pull request, along with a description of the finer details. If we're adding this page, then we might title it ["Implement Internal Docs Collection"](https://github.com/uclaacm/teach-la-website/pull/68). For the description, we might describe the files added and any modifications to existing code.

Once your pull request is submitted, you'll notice that you can't immediately merge it (i.e., have your changes added to the source code). This is because we enforce a mandatory code review from a maintainer prior to merging. Code review is an essential part of development. What it means is that someone who owns or manages the repository looks over your changes to make sure that nothing breaks, everything works as expected, and that - in some cases - your coding style is up to the project's standards.

### Code Review
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel free to link to the official GH docs for this as well.


To request review from a project maintainer, simply click on the "review" sidebar on your newly-created pull request.

![selecting a reviewer for the pull request]({{ site.baseurl }}/img/docs/dev-setup-reviewers.png)

From here, we can request the review of project maintainers or fellow peers. You'll get a notification on GitHub after a the reviewer you requested publishes their response.

A code review will appear on your pull request on GitHub as a comment, with specific comments on parts of your code. A review can either approve (ready to merge), deny (needs some changes before it is ready), or remain neutral (often an interim review) on your changes. This gives way to collaborative, iterative development.

### Merging!

Once the review process is complete and your pull request is approved, you will have the option to "merge pull request" at the bottom of the conversation thread! Once you do this, your changes will be reflected on either the `master` or `main` branch and reflected on the [live website](https://teachla.uclaacm.com) you're currently working on!

## Next Steps

Expand All @@ -307,9 +268,7 @@ Next steps:
* Learning and using React
* Checking out the Teach LA Editor!

Resources:
* [React.js Tutorial](https://reactjs.org/tutorial/tutorial.html)
* [Teach LA's Learning Labs Crash Course YouTube Series](https://www.youtube.com/channel/UCwTqwgA4thysNbB2kNYsCIw)
Be sure to check out our [Dev Team Resources]({{ site.baseurl }}/dev/resources) page for our list of helpful guides!

## Appendix

Expand All @@ -327,61 +286,6 @@ If you want to make a commit, simply write a message in the box below your list

To `push` and `pull`, use the sync button in the interface.

### Installing Ruby with RVM

[RVM](http://rvm.io/) stands for the **Ruby Version Manager**. It is a handy shell script that lets us keep multiple versions of the Ruby interpreter on our computer without breaking any existing ones! The only catch? It only works on UNIX-based operating systems. That means that it won't work on Windows by default, but it **will** work on WSL.

Following along with the installation guide available on [their website](http://rvm.io/rvm/install) is usually enough, but there are a few hitches you might run into along the way. Here's our version of the installation guide:

First we need to add the PGP keys of the project maintainer to ensure that the installer we download isn't malicious. We can do this with:

```sh
gpg --keyserver hkp://pool.sks-keyservers.net \
--recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \
7D2BAF1CF37B13E2069D6956105BD0E739499BDB
```

This assumes that you have `gpg` installed on your device. It is standard on OSX (Macs), and *highly recommended* on Linux distributions. If you don't have `gpg` installed for some reason on your system, you likely know what you are doing. To reinstall it, use the packages provided on the [GnuPG](https://gnupg.org/download/) website.

Now, we can install RVM by running the following:

```sh
\curl -sSL https://get.rvm.io | bash -s stable --ruby
```

Following installation, you should see some output like:

```sh
* To start using RVM you need to run `source /home/myuser/.rvm/scripts/rvm`
in all your open shell windows, in rare cases you need to reopen all shell windows.
```

If you see something else, then the installation may have went haywire. No worries! Most issues can be resolved by reinstalling RVM using the steps above. If that doesn't work, then try clearing your existing installation of RVM with `rm -rf ~/.rvm` and then reinstalling.

For RVM to work properly, we are required to place its binaries at the first position in our `$PATH` environment variable, and to run `source /home/myuser/.rvm/scripts/rvm` to get it to work properly. This can be solved by appending lines to our `.bashrc` (or `.zshrc`) with some simple shell commands:

```sh
# prepend to PATH:
echo "export PATH=${HOME}/.rvm/bin:${PATH}" >> ${HOME}/.bashrc

# load rvm into every shell
echo "source ${HOME}/.rvm/scripts/rvm" >> ${HOME}/.bashrc

# load rvm
source ${HOME}/.rvm/scripts/rvm
```

Now, log out and back in to your terminal (close and reopen it, if using a GUI), and choose a version of Ruby to install and use:

```sh
rvm install 3.0.0
rvm use 3.0.0
```

If either of these commands output any kind of error, then you should retry our installation guide.

You're all set for Ruby development! If you followed this chapter while you were going through the docs for the first time, then you should be able to resume your setup process from [the installing dependencies header](#installing-dependencies).

### Installing WSL

The **Windows Subsystem for Linux (WSL)** is a way to run native Linux applications from within Windows, by compartmentalizing a Linux kernel on your Windows installation. It opens up the whole of native Linux tools and programs to you without sacrificing the more familiar GUI and software compatability of Windows. Here's how to install it:
Expand Down
40 changes: 29 additions & 11 deletions _docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@
layout: default
---

<h1 class="title text-2x">Everything you need to know about this website.</h1>
<h1 class="title text-2x">Everything you need to know about getting started with Teach LA's dev team.</h1>
<p class="text-15x">
Learn how to set up your development environment, add yourself to the teams page, add or remove classes, resources, and more! <b>No previous coding experience required</b>!
Learn how to set up your development environment for our website or projects, add yourself to the
teams page, add or remove classes/resources, and more! <b>No previous coding experience required</b>!
</p>

<h2 class="title">Get Set Up</h2>
<h2 class="title">Developer Set Up</h2>
<p class="text-15x">
Follow along with our <a class="tla-link" href="{{site.baseurl}}/docs/dev-setup">in-depth setup walkthrough...</a>
Follow along with our <a class="tla-link" href="{{site.baseurl}}/docs/dev-setup">in-depth setup walkthrough</a>
to get familiar with your shell and GitHub, which every person on the dev team needs!
</p>
<p>
...or, if you're already a command-line guru and assuming you have git and Ruby:
Expand All @@ -25,10 +27,11 @@ <h2 class="title">Get Set Up</h2>
$ bundle exec jeykll serve</code>
</pre>

<h2 class="title">Add Yourself to the Teams Page</h2>

<h2 class="title">Website Development Set Up</h2>
<p class="text-15x">
Follow along with <a class="tla-link" href="{{ site.baseurl }}/docs/static-setup">our guide</a> to leave your mark on the club's team page!
Follow along with <a class="tla-link" href="{{ site.baseurl }}/docs/static-setup">our website set-up guide</a>
to get your development environment set-up for working on our website
and to leave your mark on the club's team page!
</p>

<div class="TEAM-SPECIAL">
Expand All @@ -55,14 +58,29 @@ <h3 class="no-margin title">Your Name</h3>
</div>
</div>

<h2 class="title">Project Development Set Up</h2>
<p class="text-15x">
Check out our <a class="tla-link" href="{{site.baseurl}}/docs/project-setup">project set-up guide</a>
to get your development environment set-up to work on our projects!
</p>





<h2 class="title">Going Forward: Exploring Teach LA's Resources</h2>
<p>
After adding yourself to the website, it's time to explore some of the other resources offerred by Teach LA! A great place to start is <a class="tla-link" href="https://github.com/uclaacm/learning-lab-crash-course-su20">our web development crash course</a> repo on GitHub.
After adding yourself to the website, it's time to explore some of the
<a class="tla-link" href="{{site.baseurl}}/dev/resources">Dev Team Resources</a>
offered by Teach LA!
</p>

<h2 class="title">And Beyond: Take on an Issue!</h2>
<p>
After you've familiarized yourself with the development tools, and brushed up on web development, you are free to work on whatever you'd like!
We personally recommend that you take on an issue in our repositories tagged with <a class="tla-link" href="https://github.com/uclaacm/teach-la-website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">"good first issue"</a> before really digging your heels in.
After you've familiarized yourself with the development tools,
and brushed up on web development, you are free to work on whatever you'd like!
We personally recommend that you take on an issue in our repositories tagged with
<a class="tla-link" href="https://github.com/uclaacm/teach-la-website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">"good first issue"</a>
before really digging your heels in.
</p>
</div>

Loading