Skip to content
This repository has been archived by the owner on May 20, 2018. It is now read-only.

Developing for this project

Jump to bottom
Jarrett Keifer edited this page May 23, 2016 · 3 revisions

Developing for this project

This project makes use of many technologies to make development easier. However, this also means the project has many dependencies. Namely, the project makes use of the following (this is not a comprehensive list):

  • typescript
  • angular.js & angular packages
  • bootstrap/sass

Development requires many dev tools to manage these dependencies and run the build process. Therefore, the development dependencies include:

  • node.js & npm
  • gulp & gulp plugins
  • bower
  • typings

Notes on the project initialization and structure

Yeoman was used to create the base project, specifically the [angular-typescript-gulp] (https://github.com/danwild/generator-angular-typescript) generator. I do not have any background with angular so I am trusting the project structure this generator laid out.

All the source files for the project are in public/src. Here, each directory represents an angular module. For example, the main app module is in app/, and the auth module is in auth/. Each module directory contains a .ts file of the same name with the module definition, and can have services/, controllers/, and /views directories for each of those pertaining to the module.

If the last sentence was confusing, then you don't know angular. Start here: https://docs.angularjs.org/guide/concepts. Also checkout http://campus.codeschool.com/courses/shaping-up-with-angular-js/.

Most of this project's dependencies are included in the git repo. Including these files is a fairly controversial topic, but I made the decision to keep them. This article makes good arguments for when and when not to include dependencies with a project, and I happen to share the author's opinions on the subject. While advances in tools like bower and npm have made some of these points less relevant (shrinkwrapping and whatnot), I believe including the dependencies makes deployment and development easier for those that don't have specific knowledge of these tools. Keeping the dependencies in the repo also helps avoid future issues where packages may be deleted or changed. The larger space requirements seems a reasonable trade-off for these advantages.

The only dependencies not included in the repo are those which need to be installed at the global level, such as npm, bower, and gulp. Please see below for the steps to setup a development environment which discusses installing these.

gulp vs grunt

Based on a quick overview of these two competing technologies, I determined gulp was the best choice for a new project that was not already dependent on grunt. I, personally, do not have much experience with either, so the basis of this choice was primarily my perception of which appeared to have the best balance of user-friendliness and power. gulp won. If you're a grunt diehard I'm sorry.

Setting up a development environment

As most dependencies are included in the repository, setting up a development environment requires only installing global dependencies and cloning the repository.

  1. Install the LTS node.js release for your platform using your preferred method (download the package, or on mac use brew.)

  2. Once node is install npm, the node package manager, will be available for use on the system. Use npm to install the remaining dependencies bower, gulp, and typings:

    npm install -g bower gulp typings

    Note that I currently use the following versions of these three packages:

  3. Clone this repository after cd'ing to your desired working directory: git clone [email protected]:PSU-CSAR/django-ebagis-ui.git

At this point you should be set to start developing.

Developing for ebagis

As mentioned, the source for the project is in public/, with the angular source in public/src specifically. For most development tasks, you should only need to work in the public/ directory.

Also mentioned, gulp is the build tool used for this project. Running gulp will build the project, start a local webserver running on port 3000, then watch the source for changes. This single command provides everything a developer might need for almost all tasks, aside from pushing changes to the deploy branch.

Once you have made some changes and are ready to deploy them, obviously commit the source changes using git, then deploy the code using gulp deploy. At this point, the deploy command will build the project, then it will take the contents of public/ and push them to the deploy branch on origin upstream. It is planned to revise the deploy command to require an argument that is the branch name to deploy to, both to prevent unintended deploys and to allow multiple deploy branches for dev, test, staging, and production.

Any deployed changes will need to be pulled on down on any projects using them as no commit hooks are currently in place to allow automated updating of those resources. This is also an area of potential improvement.

Clone this wiki locally