Skip to content

Latest commit

 

History

History
183 lines (160 loc) · 10.2 KB

DEVELOPER-WORKFLOW.md

File metadata and controls

183 lines (160 loc) · 10.2 KB
Raw

DEVELOPER-WORKFLOW

This file describes the development workflow for the Mushroom Observer project. We use a distributed workflow, known as "Integration-Manager" or "forking" workflow. See Workflow below.

This file assumes that you followed the directions in README.md through Create a user in the new instance of MO including setting up the MO development environment by running mo-dev /vagrant.

Preliminaries

Configure Github and Git

  • On Github, fork (create your own copy of) the Official MO Repo.
  • In a new Terminal window on your local machine, switch to the mushroom-observer directory
    cd developer-startup/mushroom-observer
  • Add your personal Github repository as a remote repository
    git remote add personal [email protected]:<YourGitUserName>/mushroom-observer.git

The Development Cycle

Sync with the Official MO Repo

Synchronize your local machine, the VM, and your personal Github to the Official MO Repo. Use a Git GUI or on your local machine:

git checkout main
git fetch origin
git merge origin/main
git push personal main

Create a personal, feature branch

  • Create a new feature branch for your changes, and switch to that branch. Use a Git GUI or on your local machine:
    git checkout -b <mybranch-name>
    for example, git checkout -b myfixes
  • If you are working on an issue listed in the MO project issue tracker, update the issue there.

Edit code

Your local machine's developer-startup directory has a 'mushroom-observer' sub-directory. This is a 'shared folder' which mirrors /vagrant/mushroom-observer on the VM. You can change code on one machine and it will appear on the other.

Switching Between Branches With Different Schemas

Sometimes it becomes necessary to switch between branches having different schemas after you have created data for one branch. You can use the following procedure:

  • Before switching, clean the VM. On the VM:
    script/clean_dev_vm
    This cleans out all sorts of auto-generated files and other cruft from the development VM and drops the databases.
  • Switch branches using a Git GUI or git checkout <other branch>
  • Run mo-dev again in the root directory of the VM. On the VM:
    cd ~; mo-dev /vagrant
  • Switch back to the mushroom-observer directory. On the VM:
    cd /vagrant/mushroom-observer/
  • and you're good to go.

Commit your changes to your personal machine

Work on your branch, e.g. myfixes. Make commits using a Git GUI or Git terminal commands on your local machine.

When you are done with all your changes and are ready to contribute them to the Project, make sure they are all committed locally. Use a Git GUI or on your local machine:
git commit -a -m "insert commit message"
For some ideas about writing commit messages, see How to Write a Git Commit Message

Contribute your changes to the MO Project

Re-sync with the Official MO Repo

Make sure that your local commits are compatible with any changes to the Official MO Repo since you last synced:

  • Replay your local fixes on top of the Official MO Repo. Use a Git GUI or on your local machine:
    git checkout myfixes
    git pull --rebase origin main
  • Fix any conflicts.

Push your changes to your personal Github repository

Use a Git GUI or on your local machine
git checkout myfixes
git push personal myfixes

Create a Pull Request (PR)

  • Go to your personal Github repository and click on "Pull Request".
  • Switch to your feature branch
  • Choose your feature branch in your personal Github repo as the source branch
  • Choose origin repo "main" as the destination branch.
  • Check the "Allow edits from maintainers" checkbox. See Improving collaboration with forks
  • In the PR description please:
    • Say what problem/feature the PR addesses, including a link to to any Pivotal story or MO Developers disussion;
    • Include a manual testing script; and
    • Mention any unusual aspects of the code.
  • For more information about PRs, see Using pull requests.

Loading a Snapshot of the Live Database (optional)

We periodically create a snapshot of the live database. You can optionally load this to your development VM:

rake db:drop
mysql -u root -p < db/initialize.sql

When asked for the password, use root.
Warning: The next line can take a long time to execute. (It used to take 20 minutes on my machine. JDC)

gunzip -c checkpoint_stripped.gz | mysql -u mo -pmo mo_development
rails db:migrate
rails lang:update

Finally, delete checkpoint_stripped.gz and clean.sql from the mushroom-observer directory.

In this cleaned snapshot, all passwords have been reset to "password".

Snapshot migration error, table already exists

Under some conditions migrating after you've loaded the snapshot will cause an error like the following. This can happen with the first migration, or many migrations later if you switch branches.

= 20170423010922 CreateArticles: migrating ===================================
-- create_table(:articles)
rake aborted!
StandardError: An error has occurred, all later migrations canceled:

Mysql2::Error: Table 'articles' already exists: CREATE TABLE `articles` (`id` int(11) auto_increment PRIMARY KEY, `title` varchar(255), `body` text, `user_id` int(11), `rss_log_id` int(11), `created_at` datetime NOT NULL, `updated_at` datetime NOT NULL) ENGINE=InnoDB

The solution is to drop the offending table. An easy way to do this is via the mysql interpreter.

$ mysql -u mo -pmo
mysql> use mo_development;
mysql> drop table articles;
mysql> exit

(For a longer discussion, see Pivotal Story #147019977.)

Other

Follow MO development

Consider subscribing/joining to follow the project more closely

Notes

Workflow

Integration-Manager-Workflow-Diagram We use "integration-manager" or "forking" workflow.

  • Each developer:
    • Clones the official MO repository to the developer's local machine;
    • On the developer's local machine, creates a personal feature branch for the developer's changes;
    • Pushes the personal branch from the local machine to the developer's personal, publicly readable copy (fork) on Github;
    • Creates a pull request in Github.
  • A manager then
    • merges the developer's changes to the manager's local machine;
    • if the developer's changes are acceptable, pushes them to the official MO repository.

For more information, see Integration-Manager Workflow and Forking Workflow; cf. What's the Workflow.

Git GUIs

Some developers primarily (or exclusively) use a Git GUI -- as opposed to typing Git commands at the terminal. Two free GUIs that have been found useful on the Mac are: GitHub GUI and SourceTree.

Pull Requests by Others

One way to get a copy and test other developers' Pull Requests is by following the instructions in Get the Changes and Experiment with the Changes (both in the ADMIN-WORKFLOW.md file in this repository.)