search

appirio-tech / tc-site

topcoder member-facing site
3 stars 19 forks source link

readme

Topcoder.com Wordpress site

Overview

The [topcoder] site is an AngularJS app backed by multiple REST APIs. The site stands as the primary entry point for a member into www.topcoder.com, and serves the majority of functions on the www.topcoder.com domain.

Functions on the site are handled by a variety of REST APIs/services:

All APIs are authorized by a JWT (internally called tcjwt) issued by auth0. Site login takes place by a coordination of authentication by auth0 and our legacy site. All data in the views, as well as actions that take place on the site, should be coordinated by its respective API, no session state can be relied upon from the legacy backend (wordpress).

The site has some legacy components that are being refactored:

Below, we explain some of the nuts and bolts to help new developers get up-and-running.

Local Env Setup

The easiest way to get running fast is by running our vagrant development environment.

Otherwise, to install the site locally there are a few setup steps.

Environmental Variables

After any change to your config.json, be sure to update the CSS/JS registry

Environment variables are loaded form config.json. The config.json file is built during grunt process, so be aware, when you run grunt, it will overwrite changes you have made.

The following command line options can be used ot customize the build:

Javascript and CSS

There should be no Javascript or CSS in PHP template files; that is, all Javascript and CSS should be in separate (and appropriately placed) *.js and *.css files. The only acceptable time to include Javascript in a PHP template is to pull data into a Javascript variable from PHP. You can break up Javascript and CSS into as many files as is useful for organization without impacting performance, since we minify and concatenate all our Javascript and CSS files in production (that said, all your JS (especially Angular code) should be minification-safe).

...that said, we should probably teach you how to

add new JS and CSS files

Our JS and CSS files are concatenated and minified by Grunt, which is configured in Gruntfile.js in the root of this repo. The grunt process pulls in the file wp-content/themes/tcs-responsive/config/script-register.json to determine which files are to be concatenated and minified, as well as what templates they are to be loaded on.

Each end-product of minification and concatenation is called a "package". Each package has three properties: name, which is a required string that should match the name of the package (i.e., the name of the property used to reference the package); js, which is an array of strings referenced relative to wp-content/themes/tcs-responsive/js; and css, which is an array referenced relative to wp-content/themes/tcs-responsive/css. After the "packages" section, there is also a "templates" section that gives a mapping of package names to PHP templates. This determines which packages will be loaded for which templates.

While there is much JS and CSS that is more or less site-wide, you should determine what CSS and JS your package uses and exclude everything else so as to ensure optimal performance.

Example:

Loading home page:

  1. Template used: front.php
  2. The script loader will look at script-register.js and see that front.php is not included the "templates" object.
  3. Since this page is not in the "templates" object, the page will default to using the "default" JS/CSS package. If minification is being used, this means default.min.js and default.min.css will be used; otherwise, all the files listed will be loaded individually.

For more information see lib/scripts.php

Minification and the CDN

There are new theme options to control JS/CSS optimizations. The options can be found at /wp-admin/themes.php?page=options.php.

Development Guidelines

Code Style

These are the formating rules our code should follow.

AngularJS

Git Information

Branch Model

To contribute to this repository, you must follow our branch model – even if you're contributing from a fork of the repo. A branch for a given feature takes the name format <developer name>-<issue or feature ID>-<description>. Branches should be off of the tc-site master branch. When you are done with your changes to this branch, you should submit a merge request against our master branch.

Every Friday (sometimes postponed until Sunday), the master branch gets pushed to our QA server at http://tcqa1.topcoder.com. If you need to make changes to your code that is already in QA, you will need to do a pull against the most recent release branch, which will look like TC-<date> (where <date> is the date of this coming Thursday – when our releases happen). The branch you use for these changes should have the same format as usual, but something like -fix should be appended to the end.

Challenge Submission and Review

Registrants in a challenge should submit their work in Git as merge requests. Challenge submissions should be in the form of a git patch. We will follow the https://drupal.org methodology for patches. This description of a patch was taken from drupal.org:

Patches are pieces of code that solve an existing issue. In fact, patches describe the changes between a before and after state of either a module or core. By applying the patch the issue should no longer exist.

There is extensive documentation about how to create and apply patches. There are instructions https://drupal.org/patch

Final Submissions should be in the form of a pull request. See the section on Branch Model for more information

Recommend Workflow for Working on a Challenge

These are some recommended workflows to help you get started with Git. Once you become more familiar with Git, you can modify the workflow to fit your style.

Working on a challenge

  1. Clone the repository. git clone https://gitlab.com/topcoderinc/tc-site.git
    • If you already have a repository setup, be sure to pull down the latest changes: git pull origin master
  2. Create a new branch: git checkout -b <branch_name>
  3. Make your changes, add new files, etc.
  4. Commit changes as you make them with descriptive commit messages
  5. If you create new files be sure to add them to git first git add <file name>

Submitting a patch to a challenge

  1. Pull down the latest code: git fetch origin
  2. Merge in the latest changes from the master branch: git merge master
  3. Create a patch against the master branch: git diff master > patchn_ame.patch
  4. Submit the patch to the challenge

Creating a pull request for for final approval

  1. Create a fork of the project on Gitlab if you haven't already.
  2. Add the new remote to your local git repo. git remote add <remote_name> <remote_url> for example git remote add mine git@gitlab.com:indytechcook/tc-site.git.
  3. Make sure all of the code is committed to the branch you were working on above.
  4. Verify code is ready to be pushed by running git status
  5. Push code to remote repository. git push <remote_name> <branch_name>
  6. Create a pull request from your branch against the master branch on the main repository.

More Git help

More Git help can be found on several places online including the following:

If you prefer to use a GUI, I recommend using SourceTree. SourceTree is available on Mac and Windows.
http://www.sourcetreeapp.com/