Developer guide: getting started

How to start developing

We develop buttonmen using this repo, our Jenkins CI server for testing, and private development environments based on either Vagrant/VirtualBox or a native AMP stack.

See https://github.com/buttonmen-dev/buttonmen/wiki/Developer-guide:-architecture for an overview of the architecture and processes. This page is a todo list for getting setup.

Get some accounts

1. Sign up for a github account at: https://github.com/signup
2. Ask to be subscribed to the mailing list buttonmen-committers@keyfitz.org

Fork a repository

1. Login to github
2. Browse to the main buttonmen repository: https://github.com/buttonmen-dev/buttonmen
3. Click the "Fork" button, and follow the instructions. For convenience, name your primary fork "buttonmen" also, so it will show up at: https://github.com/$yourusername/buttonmen

Setup CircleCI to test your github changes

1. Browse to https://circleci.com/signup/
2. Click "Sign Up with GitHub"
3. Sign in with your github account and follow the prompts

Note that this does give CircleCI OAuth access to your github account. You can browse to https://github.com/settings/security at any time to see what has been done with the access. Let us know if you have concerns about this and would rather not do it.

Setup your git development environment

Do all of this on your desktop or laptop, or wherever you will be doing local development.

1. Clone a copy of your forked repository:

username=<your username>
git clone https://github.com/$username/buttonmen.git

2. Add the primary fork as a git remote named "upstream", so you'll be able to merge in other people's changes:

cd buttonmen
git remote add upstream https://github.com/buttonmen-dev/buttonmen.git
git fetch upstream
git merge upstream/master

There is a lack of consensus about how to setup git repos. See one of a couple of documents:

• Documents that are written with the idea that you'll use one local directory for all of your git work, and switch between branches in that directory. This works well with a Netbeans/AMP-type workflow:
  • https://github.com/buttonmen-dev/buttonmen/wiki/Developer-guide:-general-workflow: a variety of git commands for various parts of the pull request lifecycle
  • https://github.com/buttonmen-dev/buttonmen/wiki/Developer-guide:-james-git-crib-sheet: James's git crib sheet
• Documents that are written with the idea that you'll use a separate local directory for each branch. This works well with a Vagrant/VirtualBox workflow, because you can keep multiple different versions of the site around at once:
  • (Chaos's git workflow notes)[https://github.com/buttonmen-dev/buttonmen/wiki/Chaos%27s-git-workflow]

Setup a place to run the code

In principle, all you need to run the ButtonWeavers code is any sort of Apache, MySQL, PHP stack. In practice:

• The production and development webservers, http://www.buttonweavers.com and http://dev.buttonweavers.com, run on Ubuntu, and are managed remotely by vagrant using puppet recipes which live in the codebase under deploy/vagrant/
• You can use the same recipes to run a test webserver using VirtualBox --- this setup is described in deploy/vagrant/README. It works well on a Mac desktop, should work well on a Linux desktop, and is possible but difficult to setup under Windows
• You can setup an AMP stack for testing --- this setup is described for Windows in setting up a WAMP stack, and a similar approach would work under Linux or Mac

Talk to other devs

We hang out on a Discord channel, and there is usually someone there. If you're getting set up, that's a great place to come by and get debugging help or discuss ideas. Ping one of the developers for an invite link.