mirror of
https://github.com/openfoodfoundation/openfoodnetwork
synced 2026-01-24 20:36:49 +00:00
Merge pull request #2415 from oeoeaio/update-readme
Update README.md and add GETTING_STARTED.md
This commit is contained in:
Pau Pérez Fabregat
GitHub
@@ -1,28 +1,17 @@
|
||||
# Contributing
|
||||
We love pull requests from everyone. Any contribution is valuable, but there are two issue streams that we especially love people to work on:
|
||||
|
||||
1) Our delivery backlog, is managed via a ZenHub board (ZenHub extensions are available for most major browsers). We use a Kanban-style approach, whereby devs pick issues from the top of the backlog which has been organised according to current priorities. If you have some time and are interested in working on some issues from the backlog, please make yourself known on the [#dev](https://openfoodnetwork.slack.com/messages/C2GQ45KNU) channel on Slack and we can direct you to the most appropriate issue to pick up.
|
||||
1) Our delivery backlog, is managed via a ZenHub board (ZenHub extensions are available for most major browsers). We use a Kanban-style approach, whereby devs pick issues from the top of the backlog which has been organised according to current priorities. If you have some time and are interested in working on some issues from the backlog, please make yourself known on the [#dev][slack-dev] channel on Slack and we can direct you to the most appropriate issue to pick up.
|
||||
|
||||
2) Our list of bugs and other self-contained issues that we consider to be a good starting point for new contributors, or devs who aren’t able to commit to seeing a whole feature through. These issues are marked with the `# good first issue` label.
|
||||
|
||||
## Set up
|
||||
|
||||
Set up your local development environment by following the appropriate guide from the `Development environment setup` section in the [developer wiki](https://github.com/openfoodfoundation/openfoodnetwork/wiki).
|
||||
Please follow the [GETTING_STARTED](GETTING_STARTED.md) guide to set up your local dev environment.
|
||||
|
||||
Add an `upstream` remote that points to the main repo:
|
||||
This guide assumes that the git remote name of the main repo is `upstream` and that your fork is named `origin`.
|
||||
|
||||
cd ~/location-of-your-local-ofn-repo
|
||||
git remote add upstream https://github.com/openfoodfoundation/openfoodnetwork
|
||||
|
||||
If you haven't already done so, fork this repo using the `Fork` button in the top-right corner of this screen. Then ensure that your fork is listed as the `origin` remote on your local machine.
|
||||
|
||||
git remote set-url origin https://github.com/your-username/openfoodnetwork
|
||||
|
||||
Fetch the latest version of `master` from `upstream` (ie. the main repo):
|
||||
|
||||
git fetch upstream master
|
||||
|
||||
Create a new branch on your local machine for (based on `upstream/master`):
|
||||
Create a new branch on your local machine to make your changes against (based on `upstream/master`):
|
||||
|
||||
git checkout -b branch-name-here --no-track upstream/master
|
||||
|
||||
@@ -70,5 +59,6 @@ From here, your pull request will progress through the [Review, Test, Merge & De
|
||||
[rebase]: https://www.atlassian.com/git/tutorials/merging-vs-rebasing/workflow-walkthrough
|
||||
[travis]: https://travis-ci.org/
|
||||
[semaphore]: https://semaphoreci.com/
|
||||
[slack-dev]: https://openfoodnetwork.slack.com/messages/C2GQ45KNU
|
||||
[ofn-transifex]: https://www.transifex.com/open-food-foundation/open-food-network/
|
||||
[i18n]: https://github.com/openfoodfoundation/openfoodnetwork/wiki/i18n
|
||||
|
||||
96
GETTING_STARTED.md
Normal file
96
GETTING_STARTED.md
Normal file
@@ -0,0 +1,96 @@
|
||||
### Getting Started
|
||||
|
||||
This is a general guide to setting up an Open Food Network development environment on your local machine.
|
||||
|
||||
The following guides are located in the wiki and provide more OS-specific step-by-step instructions:
|
||||
|
||||
- [Ubuntu Setup Guide][ubuntu]
|
||||
- [macOS Sierra Setup Guide][sierra]
|
||||
- [OSX El Capitan Setup Guide][el-capitan]
|
||||
|
||||
### Dependencies
|
||||
|
||||
* Rails 3.2.x
|
||||
* Ruby 2.1.5
|
||||
* PostgreSQL database
|
||||
* PhantomJS (for testing)
|
||||
* See Gemfile for a list of gems required
|
||||
|
||||
If you are likely to need to manage multiple version of ruby on your local machine, we recommend version managers such as [rbenv](https://github.com/rbenv/rbenv) or [RVM](https://rvm.io/).
|
||||
|
||||
For those new to Rails, the following tutorial will help get you up to speed with configuring a [Rails environment](http://guides.rubyonrails.org/getting_started.html).
|
||||
|
||||
### Get it
|
||||
|
||||
If you're planning on contributing code to the project (which we [LOVE](CONTRIBUTING.md)), it is a good idea to begin by forking this repo using the `Fork` button in the top-right corner of this screen. You should then be able to use `git clone` to copy your fork onto your local machine.
|
||||
|
||||
git clone https://github.com/YOUR_GITHUB_USERNAME_HERE/openfoodnetwork
|
||||
|
||||
Jump into your new local copy of the Open Food Network:
|
||||
|
||||
cd openfoodnetwork
|
||||
|
||||
And then add an `upstream` remote that points to the main repo:
|
||||
|
||||
git remote add upstream https://github.com/openfoodfoundation/openfoodnetwork
|
||||
|
||||
Fetch the latest version of `master` from `upstream` (ie. the main repo):
|
||||
|
||||
git fetch upstream master
|
||||
|
||||
### Get it running
|
||||
|
||||
When ready, run `script/setup`. If the script succeeds you're ready to start developing. If not, take a look at the output as it should be informative enough to help you troubleshoot.
|
||||
|
||||
If you run into any other issues getting your local environment up and running please consult [the wiki](wiki).
|
||||
|
||||
If still you get stuck do not hesitate to open an issue reporting the full output of the script.
|
||||
|
||||
Now, your dreams of spinning up a development server can be realised:
|
||||
|
||||
bundle exec rails server
|
||||
|
||||
To login as Spree default user, use:
|
||||
|
||||
email: spree@example.com
|
||||
password: spree123
|
||||
|
||||
### Testing
|
||||
|
||||
Tests, both unit and integration, are based on RSpec. To run the test suite, first prepare the test database:
|
||||
|
||||
bundle exec rake db:test:prepare
|
||||
|
||||
Then the tests can be run with:
|
||||
|
||||
bundle exec rspec spec
|
||||
|
||||
The project is configured to use [Zeus](zeus) to reduce the pre-test startup time while Rails loads. See the [Zeus GitHub page](zeus) for usage instructions.
|
||||
|
||||
Once [npm dependencies are installed](karma), AngularJS tests can be run with:
|
||||
|
||||
./script/karma run
|
||||
|
||||
If you want karma to automatically rerun the tests on file modification, use:
|
||||
|
||||
./script/karma start
|
||||
|
||||
### Multilingual
|
||||
Do not forget to run `rake tmp:cache:clear` after locales are updated to reload I18n js translations.
|
||||
|
||||
### Rubocop
|
||||
The project is configured to use [rubocop](rubocop) to automatically check for style and syntax errors.
|
||||
|
||||
You can run rubocop against your changes using:
|
||||
|
||||
rubocop
|
||||
|
||||
|
||||
[developer-wiki]: https://github.com/openfoodfoundation/openfoodnetwork/wiki
|
||||
[sierra]: https://github.com/openfoodfoundation/openfoodnetwork/wiki/Development-Environment-Setup:-macOS-(Sierra)
|
||||
[el-capitan]: https://github.com/openfoodfoundation/openfoodnetwork/wiki/Development-Environment-Setup:-OS-X-(El-Capitan)
|
||||
[ubuntu]: https://github.com/openfoodfoundation/openfoodnetwork/wiki/Development-Environment-Setup:-Ubuntu
|
||||
[wiki]: https://github.com/openfoodfoundation/openfoodnetwork/wiki
|
||||
[zeus]: https://github.com/burke/zeus
|
||||
[rubocop]: https://rubocop.readthedocs.io/en/latest/
|
||||
[karma]: https://github.com/openfoodfoundation/openfoodnetwork/wiki/Karma
|
||||
88
README.md
88
README.md
@@ -10,85 +10,22 @@ Supported by the Open Food Foundation, we are proudly open source and not-for-pr
|
||||
|
||||
We're part of global movement - get involved!
|
||||
|
||||
* Fill in this short survey to tell us who you are and what you want to do with OFN: https://docs.google.com/a/eaterprises.com.au/forms/d/1zxR5vSiU9CigJ9cEaC8-eJLgYid8CR8er7PPH9Mc-30/edit#
|
||||
* Find out more and join in the conversation - http://openfoodnetwork.org
|
||||
* Join the conversation [on Slack](slack). Make sure you introduce yourself in the #general channel
|
||||
* Head to [https://openfoodnetwork.org](https://openfoodnetwork.org) for more information about the global OFN project
|
||||
* Check out the [User Guide](https://guide.openfoodnetwork.org/) for a list of features and tutorials
|
||||
|
||||
## Contributing
|
||||
|
||||
## Getting started
|
||||
If you are interested in contributing to the OFN in any capacity, please introducing yourself [on Slack](slack), and have a look through our [Contributor Guide](contributor-guide)
|
||||
|
||||
Below are instructions for setting up a development environment for Open Food Network. More information is in the [developer wiki](https://github.com/openfoodfoundation/openfoodnetwork/wiki).
|
||||
Our [GETTING_STARTED](GETTING_STARTED.md) and [CONTRIBUTING](CONTRIBUTING.md) guides are the best place to start for developers looking to set up a development environment and make contributions to the codebase.
|
||||
|
||||
If you're interested in provisioning a server, see [the project's Ansible playbooks](https://github.com/openfoodfoundation/ofn_deployment).
|
||||
## Provisioning
|
||||
|
||||
If you're interested in provisioning a server, see [ofn-install](ofn-install) for the project's Ansible playbooks.
|
||||
|
||||
### Dependencies
|
||||
We also have a [Super Admin Guide](super-admin-guide) to help with configuration of new servers.
|
||||
|
||||
* Rails 3.2.x
|
||||
* Ruby 2.1.5
|
||||
* PostgreSQL database
|
||||
* PhantomJS (for testing)
|
||||
* See Gemfile for a list of gems required
|
||||
|
||||
|
||||
### Get it
|
||||
|
||||
The source code is managed with Git (a version control system) and
|
||||
hosted at GitHub.
|
||||
|
||||
You can view the code at:
|
||||
|
||||
https://github.com/openfoodfoundation/openfoodnetwork
|
||||
|
||||
You can download the source with the command:
|
||||
|
||||
git clone https://github.com/openfoodfoundation/openfoodnetwork.git
|
||||
|
||||
|
||||
### Get it running
|
||||
|
||||
For those new to Rails, the following tutorial will help get you up to speed with configuring a [Rails environment](http://guides.rubyonrails.org/getting_started.html).
|
||||
|
||||
When ready, run `script/setup`. If the script succeeds you're ready to start developing. If not, take a look at the output as it should be informative enough to help you troubleshoot.
|
||||
|
||||
If you run into any other issues getting your local environment up and running please consult [the wiki](https://github.com/openfoodfoundation/openfoodnetwork/wiki).
|
||||
|
||||
If still you get stuck do not hesitate to open an issue reporting the full output of the script.
|
||||
|
||||
Now, your dreams of spinning up a development server can be realised:
|
||||
```
|
||||
bundle exec rails server
|
||||
```
|
||||
To login as Spree default user, use:
|
||||
```
|
||||
email: spree@example.com
|
||||
password: spree123
|
||||
```
|
||||
### Testing
|
||||
|
||||
Tests, both unit and integration, are based on RSpec. To run the test suite, first prepare the test database:
|
||||
|
||||
bundle exec rake db:test:prepare
|
||||
|
||||
Then the tests can be run with:
|
||||
|
||||
bundle exec rspec spec
|
||||
|
||||
The site is configured to use
|
||||
[Zeus](https://github.com/burke/zeus) to reduce the pre-test
|
||||
startup time while Rails loads. See the Zeus github page for
|
||||
usage instructions.
|
||||
|
||||
Once [npm dependencies are
|
||||
installed](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Karma), AngularJS tests can be run with:
|
||||
|
||||
./script/karma run
|
||||
|
||||
If you want karma to automatically rerun the tests on file modification, use:
|
||||
|
||||
./script/karma start
|
||||
|
||||
### Multilingual
|
||||
Do not forget to run `rake tmp:cache:clear` after locales are updated to reload I18n js translations.
|
||||
|
||||
## Credits
|
||||
|
||||
@@ -110,4 +47,9 @@ Do not forget to run `rake tmp:cache:clear` after locales are updated to reload
|
||||
|
||||
## Licence
|
||||
|
||||
Copyright (c) 2012 - 2015 Open Food Foundation, released under the AGPL licence.
|
||||
Copyright (c) 2012 - 2018 Open Food Foundation, released under the AGPL licence.
|
||||
|
||||
[slack]: https://join.slack.com/t/openfoodnetwork/shared_invite/enQtMzU2Mjk5MDc2MjA5LTM4ZTAzZjIwNzIxMmU5ODFiNWY1MTU2ZWUyNzQwNjdjNTY0N2VhY2UwOGU4ZmVjNzYyZDU2NjY3NzZkZmQwYjk
|
||||
[contributor-guide]: https://ofn-user-guide.gitbook.io/ofn-contributor-guide/who-are-we
|
||||
[ofn-install]: https://github.com/openfoodfoundation/ofn-install
|
||||
[super-admin-guide]: https://ofn-user-guide.gitbook.io/ofn-super-admin-guide
|
||||
|
||||
Reference in New Issue
Block a user