Dev contribution using GitHub

"Fork-and-Pull" Model

• We use the standard Fork-and-Pull Git/GitHub model for development. Put simply, you, a developer,
  1. make a personal fork of the DynaSim repo,
  2. make a new branch specific to a single feature or bug and code up your commits, then
  3. submit a Pull Request to either debug or dev as listed below.
• Some resources to learn Git include:
  • The official online Git book
  • Help for GitHub
• Some resources to learn the Fork-and-Pull model of Git and GitHub include:
  • A guide from Atlassian
  • This gist by Chase Pettit

Branches

• master is the "production-ready" branch for the public. Do not commit to it; let the maintainers control it.
• debug is the working branch for debugging monthly feature updates. Commit hotfixes and bug fixes to debug.
  • Make sure to add new unit test or assert statement for each bug.
• dev is the working branch for ALL other changes! New features should be merged from separate issue branches in your fork into dev branch. In other words, 99% of your work should be going onto the dev branch.
• Branches should be merged monthly according to this algorithm.
• Do NOT push your own personal branches for "production"-stable branches. If you need stability, use either debug or master.

Further Explanation of Committing Guidelines

• Your code contributions should be done this way:

  1. Make an issue for the feature you want to add.
  2. Make a feature-specific feature branch on your personal fork.
  3. Code up your changes in commits on that fork.
  4. Only when that feature is complete and tested do you make a Pull Request onto upstream/dev.
  5. If the feature is small and does NOT change the behavior of pre-existing code, go ahead and merge the PR or merge to dev directly.
  6. If the feature is even moderately-sized, ask someone for at least a preliminary code review before merging the Pull Request; in this case, at minimum make a PR.

• The only exceptions to this should be very minor bugfixes/"hotfixes" on debug or extremely trivial changes on dev or debug, like comment changes or single-line changes. NEVER change master.

• If fixing a bug takes more than a couple of lines, then make an issue out of it and treat it like you would a full feature, the only difference being you should base your bugfix on debug and commit the changes back to debug.