X-Git-Url: https://gerrit.akraino.org/r/gitweb?a=blobdiff_plain;f=src%2Ffoundation%2Fapi%2Frevel%2FCONTRIBUTING.md;fp=src%2Ffoundation%2Fapi%2Frevel%2FCONTRIBUTING.md;h=5f699ca7bb2f5ff871b09d4e99e6db85184f8c48;hb=1d1ee6961c93781e1187d8c7faa868da6b2f01f4;hp=0000000000000000000000000000000000000000;hpb=56dd5e0f2164b37b40ac1daa188ccc618b4cbd19;p=iec.git diff --git a/src/foundation/api/revel/CONTRIBUTING.md b/src/foundation/api/revel/CONTRIBUTING.md new file mode 100644 index 0000000..5f699ca --- /dev/null +++ b/src/foundation/api/revel/CONTRIBUTING.md @@ -0,0 +1,162 @@ +## Contributing to Revel + +This describes how developers may contribute to Revel. + +## Mission + +Revel's mission is to provide a batteries-included framework for making large +scale web application development as efficient and maintainable as possible. + +The design should be configurable and modular so that it can grow with the +developer. However, it should provide a wonderful un-boxing experience and +default configuration that can woo new developers and make simple web apps +straight forward. The framework should have an opinion about how to do all of the +common tasks in web development to reduce unnecessary cognitive load. + +Perhaps most important of all, Revel should be a joy to use. We want to reduce +the time spent on tedious boilerplate functionality and increase the time +available for creating polished solutions for your application's target users. + +## How to Contribute + +### Join the Community + +The first step to making Revel better is joining the community! You can find the +community on: + +* [Google Groups](https://groups.google.com/forum/#!forum/revel-framework) via [revel-framework@googlegroups.com](mailto:revel-framework@googlegroups.com) +* [GitHub Issues](https://github.com/revel/revel/issues) +* [StackOverflow Questions](http://stackoverflow.com/questions/tagged/revel) +* [IRC](http://webchat.freenode.net/?channels=%23revel&uio=d4) via #revel on Freenode + +Once you've joined, there are many ways to contribute to Revel: + +* Report bugs (via GitHub) +* Answer questions of other community members (via Google Groups or IRC) +* Give feedback on new feature discussions (via GitHub and Google Groups) +* Propose your own ideas (via Google Groups or GitHub) + +### How Revel is Developed + +We have begun to formalize the development process by adopting pragmatic +practices such as: + +* Developing on the `develop` branch +* Merging `develop` branch to `master` branch in 6 week iterations +* Tagging releases with MAJOR.MINOR syntax (e.g. v0.8) +** We may also tag MAJOR.MINOR.HOTFIX releases as needed (e.g. v0.8.1) to +address urgent bugs. Such releases will not introduce or change functionality +* Managing bugs, enhancements, features and release milestones via GitHub's Issue Tracker +* Using feature branches to create pull requests +* Discussing new features **before** hacking away at it + + +### How to Correctly Fork + +Go uses the repository URL to import packages, so forking and `go get`ing the +forked project **will not work**. + +Instead, follow these steps: + +1. Install Revel normally +2. Fork Revel on GitHub +3. Add your fork as a git remote + +Here's the commands to do so: +``` +$ go get github.com/revel/revel # Install Revel +$ cd $GOPATH/src/github.com/revel/revel # Change directory to revel repo +$ git remote add fork git@github.com:$USER/revel.git # Add your fork as a remote, where $USER is your GitHub username +``` + +### Create a Feature Branch & Code Away! + +Now that you've properly installed and forked Revel, you are ready to start coding (assuming +you have a validated your ideas with other community members)! + +In order to have your pull requests accepted, we recommend you make your changes to Revel on a +new git branch. For example, +``` +$ git checkout -b feature/useful-new-thing origin/develop # Create a new branch based on develop and switch to it +$ ... # Make your changes and commit them +$ git push fork feature/useful-new-thing # After new commits, push to your fork +``` + +### Format Your Code + +Remember to run `go fmt` before committing your changes. +Many Go developers opt to have their editor run `go fmt` automatically when +saving Go files. + +Additionally, follow the [core Go style conventions](https://code.google.com/p/go-wiki/wiki/CodeReviewComments) +to have your pull requests accepted. + +### Write Tests (and Benchmarks for Bonus Points) + +Significant new features require tests. Besides unit tests, it is also possible +to test a feature by exercising it in one of the sample apps and verifying its +operation using that app's test suite. This has the added benefit of providing +example code for developers to refer to. + +Benchmarks are helpful but not required. + +### Run the Tests + +Typically running the main set of unit tests will be sufficient: + +``` +$ go test github.com/revel/revel +``` + +Refer to the +[Travis configuration](https://github.com/revel/revel/blob/master/.travis.yml) +for the full set of tests. They take less than a minute to run. + +### Document Your Feature + +Due to the wide audience and shared nature of Revel, documentation is an essential +addition to your new code. **Pull requests risk not being accepted** until proper +documentation is created to detail how to make use of new functionality. + +The [Revel web site](http://revel.github.io/) is hosted on GitHub Pages and +[built with Jekyll](https://help.github.com/articles/using-jekyll-with-pages). + +To develop the Jekyll site locally: + + # Clone the documentation repository + $ git clone git@github.com:revel/revel.github.io + $ cd revel.github.io + + # Install and run Jekyll to generate and serve the site + $ gem install jekyll kramdown + $ jekyll serve --watch + + # Now load in your browser + $ open http://localhost:4000/ + +Any changes you make to the site should be reflected within a few seconds. + +### Submit Pull Request + +Once you've done all of the above & pushed your changes to your fork, you can create a pull request for review and acceptance. + +## Potential Projects + +These are outstanding feature requests, roughly ordered by priority. +Additionally, there are frequently smaller feature requests or items in the +[issues](https://github.com/revel/revel/issues?labels=contributor+ready&page=1&state=open). + +1. Better ORM support. Provide more samples (or modules) and better documentation for setting up common situations like SQL database, Mongo, LevelDB, etc. +1. Support for other templating languages (e.g. mustache, HAML). Make TemplateLoader pluggable. Use Pongo instead of vanilla Go templates (and update the samples) +1. Test Fixtures +1. Authenticity tokens for CSRF protection +1. Coffeescript pre-processor. Could potentially use [otto](https://github.com/robertkrimen/otto) as a native Go method to compiling. +1. SCSS/LESS pre-processor. +1. GAE support. Some progress made in the 'appengine' branch -- the remaining piece is running the appengine services in development. +1. More Form helpers (template funcs). +1. A Mongo module (perhaps with a sample app) +1. Deployment to OpenShift (support, documentation, etc) +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/)) +1. ETags, cache controls +1. A module or plugins for adding HTTP Basic Auth +1. Allowing the app to hook into the source code processing step