src/foundation/api/revel/CONTRIBUTING.md

   1 ## Contributing to Revel
   2
   3 This describes how developers may contribute to Revel.
   4
   5 ## Mission
   6
   7 Revel's mission is to provide a batteries-included framework for making large
   8 scale web application development as efficient and maintainable as possible.
   9
  10 The design should be configurable and modular so that it can grow with the
  11 developer. However, it should provide a wonderful un-boxing experience and
  12 default configuration that can woo new developers and make simple web apps
  13 straight forward. The framework should have an opinion about how to do all of the
  14 common tasks in web development to reduce unnecessary cognitive load.
  15
  16 Perhaps most important of all, Revel should be a joy to use. We want to reduce
  17 the time spent on tedious boilerplate functionality and increase the time
  18 available for creating polished solutions for your application's target users.
  19
  20 ## How to Contribute
  21
  22 ### Join the Community
  23
  24 The first step to making Revel better is joining the community! You can find the
  25 community on:
  26
  27 * [Google Groups](https://groups.google.com/forum/#!forum/revel-framework) via [revel-framework@googlegroups.com](mailto:revel-framework@googlegroups.com)
  28 * [GitHub Issues](https://github.com/revel/revel/issues)
  29 * [StackOverflow Questions](http://stackoverflow.com/questions/tagged/revel)
  30 * [IRC](http://webchat.freenode.net/?channels=%23revel&uio=d4) via #revel on Freenode
  31
  32 Once you've joined, there are many ways to contribute to Revel:
  33
  34 * Report bugs (via GitHub)
  35 * Answer questions of other community members (via Google Groups or IRC)
  36 * Give feedback on new feature discussions (via GitHub and Google Groups)
  37 * Propose your own ideas (via Google Groups or GitHub)
  38
  39 ### How Revel is Developed
  40
  41 We have begun to formalize the development process by adopting pragmatic
  42 practices such as:
  43
  44 * Developing on the `develop` branch
  45 * Merging `develop` branch to `master` branch in 6 week iterations
  46 * Tagging releases with MAJOR.MINOR syntax (e.g. v0.8)
  47 ** We may also tag MAJOR.MINOR.HOTFIX releases as needed (e.g. v0.8.1) to
  48 address urgent bugs. Such releases will not introduce or change functionality
  49 * Managing bugs, enhancements, features and release milestones via GitHub's Issue Tracker
  50 * Using feature branches to create pull requests
  51 * Discussing new features **before** hacking away at it
  52
  53
  54 ### How to Correctly Fork
  55
  56 Go uses the repository URL to import packages, so forking and `go get`ing the
  57 forked project **will not work**.
  58
  59 Instead, follow these steps:
  60
  61 1. Install Revel normally
  62 2. Fork Revel on GitHub
  63 3. Add your fork as a git remote
  64
  65 Here's the commands to do so:
  66 ```
  67 $ go get github.com/revel/revel                        # Install Revel
  68 $ cd $GOPATH/src/github.com/revel/revel                # Change directory to revel repo
  69 $ git remote add fork git@github.com:$USER/revel.git  # Add your fork as a remote, where $USER is your GitHub username
  70 ```
  71
  72 ### Create a Feature Branch & Code Away!
  73
  74 Now that you've properly installed and forked Revel, you are ready to start coding (assuming
  75 you have a validated your ideas with other community members)!
  76
  77 In order to have your pull requests accepted, we recommend you make your changes to Revel on a
  78 new git branch. For example,
  79 ```
  80 $ git checkout -b feature/useful-new-thing origin/develop    # Create a new branch based on develop and switch to it
  81 $ ...                                                        # Make your changes and commit them
  82 $ git push fork feature/useful-new-thing                     # After new commits, push to your fork
  83 ```
  84
  85 ### Format Your Code
  86
  87 Remember to run `go fmt` before committing your changes.
  88 Many Go developers opt to have their editor run `go fmt` automatically when
  89 saving Go files.
  90
  91 Additionally, follow the [core Go style conventions](https://code.google.com/p/go-wiki/wiki/CodeReviewComments)
  92 to have your pull requests accepted.
  93
  94 ### Write Tests (and Benchmarks for Bonus Points)
  95
  96 Significant new features require tests. Besides unit tests, it is also possible
  97 to test a feature by exercising it in one of the sample apps and verifying its
  98 operation using that app's test suite. This has the added benefit of providing
  99 example code for developers to refer to.
 100
 101 Benchmarks are helpful but not required.
 102
 103 ### Run the Tests
 104
 105 Typically running the main set of unit tests will be sufficient:
 106
 107 ```
 108 $ go test github.com/revel/revel
 109 ```
 110
 111 Refer to the
 112 [Travis configuration](https://github.com/revel/revel/blob/master/.travis.yml)
 113 for the full set of tests.  They take less than a minute to run.
 114
 115 ### Document Your Feature
 116
 117 Due to the wide audience and shared nature of Revel, documentation is an essential
 118 addition to your new code. **Pull requests risk not being accepted** until proper
 119 documentation is created to detail how to make use of new functionality.
 120
 121 The [Revel web site](http://revel.github.io/) is hosted on GitHub Pages and
 122 [built with Jekyll](https://help.github.com/articles/using-jekyll-with-pages).
 123
 124 To develop the Jekyll site locally:
 125
 126     # Clone the documentation repository
 127     $ git clone git@github.com:revel/revel.github.io
 128     $ cd revel.github.io
 129
 130     # Install and run Jekyll to generate and serve the site
 131     $ gem install jekyll kramdown
 132     $ jekyll serve --watch
 133
 134     # Now load in your browser
 135     $ open http://localhost:4000/
 136
 137 Any changes you make to the site should be reflected within a few seconds.
 138
 139 ### Submit Pull Request
 140
 141 Once you've done all of the above & pushed your changes to your fork, you can create a pull request for review and acceptance.
 142
 143 ## Potential Projects
 144
 145 These are outstanding feature requests, roughly ordered by priority.
 146 Additionally, there are frequently smaller feature requests or items in the
 147 [issues](https://github.com/revel/revel/issues?labels=contributor+ready&page=1&state=open).
 148
 149 1.      Better ORM support.  Provide more samples (or modules) and better documentation for setting up common situations like SQL database, Mongo, LevelDB, etc.
 150 1.      Support for other templating languages (e.g. mustache, HAML).  Make TemplateLoader pluggable.  Use Pongo instead of vanilla Go templates (and update the samples)
 151 1.      Test Fixtures
 152 1.      Authenticity tokens for CSRF protection
 153 1.      Coffeescript pre-processor.  Could potentially use [otto](https://github.com/robertkrimen/otto) as a native Go method to compiling.
 154 1.      SCSS/LESS pre-processor.
 155 1.      GAE support.  Some progress made in the 'appengine' branch -- the remaining piece is running the appengine services in development.
 156 1.      More Form helpers (template funcs).
 157 1.      A Mongo module (perhaps with a sample app)
 158 1.      Deployment to OpenShift (support, documentation, etc)
 159 1.      Improve the logging situation.  The configuration is a little awkward and not very powerful.  Integrating something more powerful would be good. (like [seelog](https://github.com/cihub/seelog) or [log4go](https://code.google.com/p/log4go/))
 160 1.      ETags, cache controls
 161 1.      A module or plugins for adding HTTP Basic Auth
 162 1.      Allowing the app to hook into the source code processing step