mirror/openseadragon
1
0
Fork 0
mirror of https://github.com/openseadragon/openseadragon.git synced 2024-11-25 06:36:11 +03:00
Code Issues Projects Releases Wiki Activity

Create CONTRIBUTING.md file. Fix #783

Browse Source
This commit is contained in:
Antoine Vandecreme 2016-01-26 18:53:23 -05:00
parent 4fea91e936
commit c032b19944
2 changed files with 81 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,77 @@
### Contributing
OpenSeadragon is truly a community project; we welcome your involvement!
When contributing, please attempt to match the code style already in the codebase.
However, we are in the process of changing our code style (see #456), so avoid spaces inside parentheses and square brackets. Note that we use four spaces per indentation stop. For easier setup you can also install [EditorConfig](http://editorconfig.org/) if your IDE is supported. For more thoughts on code style, see [idiomatic.js](https://github.com/rwldrn/idiomatic.js/).
When fixing bugs and adding features, when appropriate please also:
* Update related doc comments (we use [JSDoc 3](http://usejsdoc.org/))
* Add/update related unit tests
If you're new to the project, check out our [good first bug](https://github.com/openseadragon/openseadragon/issues?labels=good+first+bug&page=1&state=open) issues for some places to dip your toe in the water.
If you're new to open source in general, check out [GitHub's open source intro guide](https://guides.github.com/overviews/os-contributing/).
### First Time Setup
All command-line operations for building and testing OpenSeadragon are scripted using [Grunt](http://gruntjs.com/) which is based on [Node.js](http://nodejs.org/). To get set up:
1. Install Node, if you haven't already (available at the link above)
1. Install the Grunt command line runner (if you haven't already); on the command line, run `npm install -g grunt-cli`
1. Clone the openseadragon repository
1. On the command line, go in to the openseadragon folder
1. Run `npm install`
You're set, all development dependencies should have been installed and the project built...
continue reading for build and test instructions.
### Building from Source
To build, just run (on the command line, in the openseadragon folder):
grunt
If you want Grunt to watch your source files and rebuild every time you change one, use:
grunt watch
To have it watch your source files and also run a server for you to test in:
grunt dev
The built files appear in the `build` folder.
If you want to build tar and zip files for distribution (they will also appear in the `build` folder), use:
grunt package
Note that the `build` folder is masked with .gitignore; it's just for your local use, and won't be checked in to the repository.
You can also publish the built version to the site-build repository. This assumes you have cloned it next to this repository. The command is:
grunt publish
... which will delete the existing openseadragon folder, along with the .zip and .tar.gz files, out of the site-build folder and replace them with newly built ones from the source in this repository; you'll then need to commit the changes to site-build.
### Testing
Our tests are based on [QUnit](http://qunitjs.com/) and [PhantomJS](http://phantomjs.org/); they're both installed when you run `npm install`. To run on the command line:
grunt test
If you wish to work interactively with the tests or test your changes:
grunt connect watch
and open `http://localhost:8000/test/test.html` in your browser.
Another good page, if you want to interactively test out your changes, is `http://localhost:8000/test/demo/basic.html`.
You can also get a report of the tests' code coverage:
grunt coverage
The report shows up at `coverage/html/index.html` viewable in a browser.

85
README.md
View File

@ -1,9 +1,9 @@
# OpenSeadragon # OpenSeadragon
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/openseadragon/openseadragon?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/openseadragon/openseadragon?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://secure.travis-ci.org/openseadragon/openseadragon.png?branch=master)](http://travis-ci.org/openseadragon/openseadragon)
An open-source, web-based viewer for zoomable images, implemented in pure JavaScript. An open-source, web-based viewer for zoomable images, implemented in pure JavaScript.
See it in action and get started using it at http://openseadragon.github.io/. See it in action and get started using it at (http://openseadragon.github.io/).
## Stable Builds ## Stable Builds
@ -11,85 +11,8 @@ See the [GitHub releases page](https://github.com/openseadragon/openseadragon/re
## Development ## Development
If you want to use OpenSeadragon in your own projects, you can find the latest stable build, API documentation, and example code at http://openseadragon.github.io/. If you want to modify OpenSeadragon and/or contribute to its development, read on. If you want to use OpenSeadragon in your own projects, you can find the latest stable build, API documentation, and example code at (http://openseadragon.github.io/). If you want to modify OpenSeadragon and/or contribute to its development, read the [contributing guide](https://github.com/openseadragon/openseadragon/blob/master/CONTRIBUTING.md) for instructions.
### First Time Setup
All command-line operations for building and testing OpenSeadragon are scripted using [Grunt](http://gruntjs.com/) which is based on [Node.js](http://nodejs.org/). To get set up:
1. Install Node, if you haven't already (available at the link above)
1. Install the Grunt command line runner (if you haven't already); on the command line, run `npm install -g grunt-cli`
1. Clone the openseadragon repository
1. On the command line, go in to the openseadragon folder
1. Run `npm install`
You're set... continue reading for build and test instructions.
### Building from Source
To build, just run (on the command line, in the openseadragon folder):
grunt
If you want Grunt to watch your source files and rebuild every time you change one, use:
grunt watch
To have it watch your source files and also run a server for you to test in:
grunt dev
The built files appear in the `build` folder.
If you want to build tar and zip files for distribution (they will also appear in the `build` folder), use:
grunt package
Note that the `build` folder is masked with .gitignore; it's just for your local use, and won't be checked in to the repository.
You can also publish the built version to the site-build repository. This assumes you have cloned it next to this repository. The command is:
grunt publish
... which will delete the existing openseadragon folder, along with the .zip and .tar.gz files, out of the site-build folder and replace them with newly built ones from the source in this repository; you'll then need to commit the changes to site-build.
### Testing
Our tests are based on [QUnit](http://qunitjs.com/) and [PhantomJS](http://phantomjs.org/); they're both installed when you run `npm install`. At the moment we don't have much in the way of tests, but we're working to fix that. To run on the command line:
grunt test
If you wish to work interactively with the tests or test your changes:
grunt connect watch
and open `http://localhost:8000/test/test.html` in your browser.
Another good page, if you want to interactively test out your changes, is `http://localhost:8000/test/demo/basic.html`.
You can also get a report of the tests' code coverage:
grunt coverage
The report shows up at `coverage/html/index.html` viewable in a browser.
### Contributing
OpenSeadragon is truly a community project; we welcome your involvement!
When contributing, please attempt to match the code style already in the codebase. Note that we use four spaces per indentation stop. For easier setup you can also install [EditorConfig](http://editorconfig.org/) if your IDE is supported. For more thoughts on code style, see [idiomatic.js](https://github.com/rwldrn/idiomatic.js/).
When fixing bugs and adding features, when appropriate please also:
* Update related doc comments (we use [JSDoc 3](http://usejsdoc.org/))
* Add/update related unit tests
If you're new to the project, check out our [good first bug](https://github.com/openseadragon/openseadragon/issues?labels=good+first+bug&page=1&state=open) issues for some places to dip your toe in the water.
If you're new to open source in general, check out [GitHub's open source intro guide](https://guides.github.com/overviews/os-contributing/).
## License ## License
OpenSeadragon is released under the New BSD license. For details, see the file LICENSE.txt. OpenSeadragon is released under the New BSD license. For details, see the [LICENSE.txt file](https://github.com/openseadragon/openseadragon/blob/master/LICENSE.txt).
[![Build Status](https://secure.travis-ci.org/openseadragon/openseadragon.png?branch=master)](http://travis-ci.org/openseadragon/openseadragon)