ga-wdi-remote / how-to-use-this-org

READ FIRST: How to contribute, repo naming conventions, and content/solution styleguide

How to use this organization and contribute

• Contributing
• Naming Conventions
  • Repos
  • Branches
• Making Changes to Existing Content

What it is

This Organization holds repositories of lessons and daily class work, labs, homework, and installation lessons.

Contributing

Before creating a new repository search through organization to make sure your content is unique. You can search by repo topic names like lesson and homework or by topics like javascript, express, mongoose, ruby, rails,

If it is not unique

Clone the repository that contains an version of your content and make a new branch to push your content to.

see naming conventions below

If it is unique

Create a new repository with a master and a solution branch.

Label your repo with Topics by clicking the Settings tab in the organization, and clicking Repository topics.

Find your repo in the list and add the relevant tags to make the repo easily searchable from the org home page.

Be sure to definitely label your repo as either lesson, homework, lab etc and the technologies required.

Naming Conventions

Repositories

Name of the repo should start with language/tech abbreviation followed by the type of content and the name of the assignment.

examples:

js-hw-function-reps
ruby-lab-banana-stand

Once the repo is created add a description to the repository describing the content if there are things specific to the content that should be known early.

For Example:

That the lab in a repo is a multi-day assignment or dependent on the content in some other repo etc.

Branches

Every repo should have the starter code, lesson, README, instructions, examples, on the master branch.

The solution code in a solutions branch.

Iterating on existing content

If changes are updates be sure to update the master branch as well as the solution branch.

Adding a new version of existing content

Your branch name should include your name and whether it's the master or the solution.

master
<your name>-solution

Making Changes

Create an issue on the repo in question and list the problem, proposed fix, or addition and the associated branch, file, line number, etc.

The content owner can either make that change or suggest that it goes into a new version of the lesson made by you!

how-to-use-this-org's Issues

Purpose of a master branch

As referenced in #4, we might consider the naming conventions of master and solution branches.

Considering the process of scaling–say we have many teams working in this org and we want to keep all the ui-router content to one repo–there wouldn't necessarily be a master version of a lesson. But different versions that use different examples.

As we scale we might need to justify the purpose and value of a master branch vs branches named after the type of example they hold.

Thinking about documenting order

Necessary? Not necessary?

If so, what is a maintainable way to thread content while considering scaling this organization. It'd be easy for us to thread it all together once for our own benefit. But if another team were to use the content and reorder it how would that work? Or would it?

Repos/lessons should be example agnostic

For example, the ui-router repo is currently titled ng-giphy-ui-router, which is fine but the repo should really just be holding ui-router content. That the master branch holds a giphy example should be irrelevant.

This way new examples of ui-router content can be added to the branch.

Perhaps at some point we should do away with master branches all together...

https://github.com/ga-wdi-remote/ng-giphy-with-ui-router

Should we make an installation repo

That would hold installation instructions for:

• brew
• brew cask
• node
• ruby/rbenv/rails
• git
• git prompt
• mongo
• pg

as well as all the applications and tools

spectacle
hyper
slack
atom
sublime
zoom
xcode

ga-wdi-remote/lesson-culture#4

Need better naming conventions for tracking different versions of content

Currently, contribution documentation asks instructors to create a branch with their name and whether it's master or solution. This isn't particularly descriptive and doesn't inform other instructors as to what's different about that version vs another.

Possible options are using git branch descriptions using git branch --edit-description but this requires everyone set up a script to see the description since they're only listed in the git config file.

http://labs.6dglobal.com/blog/2015-02-19/taking-advantage-git-branch-descriptions/

We could create an installation script that sets this up easily.

Other options are:

1. create more verbose naming conventions for branches
2. ask that instructors create an issue that describes the lesson and the branch name