Permalink
Browse files

Adding release and infrastructure guide for CanJS

  • Loading branch information...
1 parent 8c6dd8b commit d3552603e9f20bb09be08dbdf579bd149b2cd1d7 @daffl daffl committed Oct 18, 2016
Showing with 81 additions and 315 deletions.
  1. +0 −42 can.md
  2. +11 −273 contributing.md
  3. +1 −0 docs/can-guides/Guides.md
  4. +69 −0 docs/can-guides/contribute/releases.md
View
@@ -1,42 +0,0 @@
-@page canjs CanJS
-@parent javascriptmvc 0
-
-@body
-
-This is the detailed documentation of the API for CanJS 2.3, a framework for building
-web applications that provides a lightweight inheritance system, observable
-objects and values, and a powerful MVC core with live-bound templates, among other
-resources.
-
-If you are just starting with CanJS, you may want to try our [getting started guide](../guides/Tutorial.html).
-
-CanJS is composed of modules on the left. The following are typically distributed as part of the core
-framework:
-
- - [can.Component] - widgets built on custom tags
- - [can.Construct] - inheritable constructor functions
- - [can.Control] - declarative event bindings
- - [can.Map], [can.List], [can.compute] - observable objects, list, and values.
- - [can.Model] - observes connected to a RESTful JSON interface
- - [can.view] - template loading, caching, rendering
- - [can.route] - back button and bookmarking support
-
-The following modules are typically distributed as plugins:
-
- - [can.Map::define] - control the behavior of attributes on a can.Map
- - [can.stache] - live binding templates
- - [can.Construct.proxy] - Proxy construct methods
- - [can.Construct.super] - Call super methods
- - [can.Map.delegate] - Listen to Observe attributes
- - [can.Map.setter] - Use setter methods on Map
- - [can.Map.attributes] - Define Observe attributes
- - [can.Map.validations] - Validate attributes
- - [can.Map.backup] - Backup and restore an Observe's state
- - [can.Control.plugin] - Registers a jQuery plugin function for Controls[1]
- - [can.view.modifiers View modifiers] - Use jQuery modifiers to render views[1]
-
-
-You can use it out of the box on top of jQuery, Zepto, YUI, and Mootools,
-and it's only about 20K.
-
-@api canjs
View
@@ -7,281 +7,19 @@
Thank you for contributing to CanJS! If you need any help setting up a CanJS development environment and fixing CanJS bugs, please reach out to us on the [canjs/canjs Gitter channel](https://gitter.im/canjs/canjs) or email (contact@bitovi.com). We will happily walk you through setting up your environment, creating a test, and submitting a pull request. Here is a video showing how to contribute to CanJS:
-<iframe width="662" height="372" src="https://www.youtube.com/embed/56DoykBew38" frameborder="0" allowfullscreen></iframe>
+<iframe width="662" height="372" src="https://www.youtube.com/embed/PRuueWqnpIw" frameborder="0" allowfullscreen></iframe>
-## 3.0 Changes
-
-In 3.0, nearly every module has its own repository. All code changes should go there. Issues can be submitted to `canjs/canjs`, but once we know the root of the issue, we will move it to a specific repository.
-
-## Reporting Bugs
-
-To report a bug, please visit [GitHub Issues](https://github.com/canjs/canjs/issues).
-
-When filing a bug, it is helpful to include:
-
-- Small examples using tools like JSBin. You can clone the following CanJS bins:
- - [jQuery](http://jsbin.com/venaje/1/edit?html,js,output)
- - [Zepto](http://justinbmeyer.jsbin.com/veqola/edit?html,js,output)
-- Breaking unit tests (optional)
-- Proposed fix solutions (optional)
-
-Search for previous tickets, if there is one add to that one rather than creating another. You can also post on the [Forums](http://forums.donejs.com/c/canjs) or talk to us in [gitter canjs/canjs channel](https://gitter.im/canjs/canjs).
-
-## Installing
-
-1. <a href="https://github.com/canjs/canjs/fork" target="_blank">Fork Canjs on GitHub.</a>
-2. Clone it with: `git clone git@github.com:<your username>/canjs`
-
-## Structure
-
-After installing CanJS, you’ll find a folder for each feature of CanJS: `construct`, `control`, `model`, etc.
-
-Within each feature folder, for example `construct`, you’ll find a file for:
-
-* the implementation of the feature - `construct.js`
-* a demo of the feature - `construct.html`
-* an overview documentation page - `construct.md`
-* the feature’s tests - `construct_test.js`
-* a page to run those tests - `test.html`
-
-Any plugins for that feature will be folders within the feature’s folder. Ex: `proxy`, `super`.
-
-The `can/test` folder contains:
-
-* an `index.html` page which runs all tests for each library in an iFrame.
-* a test page for each library e.g. `jquery.html` which loads dependencies using our package manager StealJS
-* a `build` folder which contains the same set of test files but for testing the build artifacts (like `can.jquery.js` etc.) you get from the download)
-* an `amd` folder which runs the same tests for the AMD modules using RequireJS
-
-The `can/util` folder contains the compatibility layer for each library.
-
-## Contributing
-
-When contributing, please include tests with new features or bug fixes in a feature branch until you're ready to submit the code for consideration; then push to the fork, and submit a pull request. More detailed steps are as follows:
-
-1. Navigate to your clone of the CanJS repository - `cd /path/to/canjs`
-2. Create a new feature branch - `git checkout -b html5-fix`
-3. Make some changes
-4. Update tests to accomodate your changes
-5. Run tests and make sure they pass in all browsers
-6. Update documentation if necessary
-7. Push your changes to your remote branch - `git push origin html5-fix`
-8. Submit a pull request! Navigate to [Pull Requests](https://github.com/canjs/canjs/pulls) and click the 'New Pull Request' button. Fill in some details about your potential patch including a meaningful title. When finished, press "Send pull request". The core team will be notified about your submission and let you know of any problems or targeted release date.
-
-## Testing
-
-CanJS has a pretty comprehensive test suite that is constantly being added to. Each module has its own tests, that can be run by opening the `test.html` in each folder. It's important that all tests pass before sending a pull request. [TravisCI](https://travis-ci.org/canjs/canjs) will determine if your commits pass the tests, but while you're developing you can run the QUnit tests locally.
-
-There are 3 ways of running your tests locally, all of which will require you to have [NodeJS](http://nodejs.org/), [npm](http://npmjs.org/), [Grunt](http://gruntjs.com/) and all of the CanJS dev dependencies installed.
-
-### Getting Set Up
-
-1. Install NodeJS & npm - [NodeJS](http://nodejs.org/) or use `brew install nodejs`
-2. Install Grunt - `npm install grunt-cli -g`
-3. Navigate to your local clone of CanJS - `cd /path/to/canjs`
-4. Install dependencies - `npm install`
-
-### Running All Tests From CLI
-
-1. Once you completed the steps above simply run `grunt test`.
-
-### Running All Tests In Browser
-
-1. `grunt connect:server:keepalive`
-2. Open [http://localhost:8000/test/](http://localhost:8000/test/) in your browser.
-
-### Running Individual Test Files
-
-1. `grunt connect:server:keepalive`
-2. Open [http://localhost:8000/](http://localhost:8000/) in your browser and then navigate to your intended file.
-
-CanJS supports the following browsers:
-
-- Chrome Current-1
-- Safari Current-1
-- Firefox Current-1
-- IE 7+
-- Opera Current-1
-
-## Documentation
-
-If your changes affect the public API, please make relevant changes to the documentation. Documentation is found either inline or in markdown files in the respective directory. In order to view your changes in documentation you will need to run the [CanJS.com site](https://github.com/canjs/canjs.com) locally and regenerate the docs.
-
-Follow the instructions on [CanJS.com gh-pages branch](https://github.com/bitovi/canjs.com/tree/gh-pages#setup) to generate documentation from your local copy of canjs.
-
-## Making a build
-
-To make a build (standalone and AMD version) you will also need to have [[NodeJS](http://nodejs.org/), [npm](http://npmjs.org/), [Grunt](http://gruntjs.com/) and all of the CanJS dev dependencies installed.
-
-### Getting Set Up
-
-1. Install NodeJS & npm - [NodeJS](http://nodejs.org/) or use `brew install nodejs`
-2. Install Grunt - `npm install grunt-cli -g`
-3. Navigate to your local clone of CanJS - `cd /path/to/canjs`
-4. Install dependencies - `npm install`
-
-After you have completed those steps simply run `grunt build` and it will put the built files in the `can/dist` directory, making them ready for download.
+For more details we have the following more in-depth contribution guides:
-## Style Guide
+ - [guides/contributing/bug-report Report a bug]
+ - [guides/contributing/feature-suggestion Suggest a feature]
+ - [guides/contributing/code Code changes]
+ - [guides/contributing/documentation Documentation improvements]
+ - [Create a plugin](https://donejs.com/plugin.html)
+ - [guides/contributing/evangelism Evangelism - Blog, meetup and conference talks]
+ - [guides/contributing/releases Releases - Maintaining CanJS]
-### Linting
-Grunt provides a `quality` task to verify some basic, practical soundness of the codebase. The options are preset.
-
-### Spacing
-Indentation with tabs, not spaces.
-
-`if/else/for/while/try` always have braces, with the first brace on the same line. For example:
-
- if(foo){
-
- }
-
-Spaces after commas. For example:
-
- myfn = function(foo, bar, moo){ ... }
-
-### Assignments
-
-Assignments should always have a semicolon after them.
-
-Assignments in a declaration should always be on their own line. Declarations that don't have an assignment should be listed together at the start of the declaration. For example:
-
- // Bad
- var foo = true;
- var bar = false;
- var a;
- var b;
-
- // Good
- var a, b,
- foo = true,
- bar = false;
-
-### Equality
-
-Strict equality checks `===` should be used in favor of `==`. The only exception is when checking for undefined and null by way of null.
-
- // Bad
- if(bar == "can"){ ... }
-
- // Good
- if(bar === "can"){ ... }
-
-If the statement is a truthey or falsey, use implied operators. Falseys are when variables return `false`, `undefined`, `null`, or `0`. Trutheys are when variables return `true`, `1`, or anything defined.
-
-For example:
-
- // Bad
- if(bar === false){ ... }
-
- // Good
- if(bar){ ... }
-
- // Good
- var foo = [];
- if(!foo.length){ ... }
-
-### Quotes
-
-Use double quotes.
-
- var double = "I am wrapped in double quotes";
-
-Strings that require inner quoting must use double outside and single inside.
-
- var html = "<div id='my-id'></div>";
-
-### Comments
-
-Single line comments go OVER the line they refer to:
-
- // We need an explicit "bar", because later in the code foo is checked.
- var foo = "bar";
-
-For long comments, use:
-
- /* myFn
- * Four score and seven—pause—minutes ago...
- */
-
-### Documentation
-
-The documentation for the different modules should be clear and consistent. Explanations should be concise, and examples of code should be included where appropriate. In terms of format and style, here are a few suggestions to keep the documentation consistent within a module and across all parts of CanJS:
-
-#### When referencing another part of CanJS, make sure to link the first reference in a section.
-
-For instance, when documenting `can.Component.scope`, the first reference to `can.Component`, `can.route`, or any other part of CanJS should be enclosed in square brackets, so that links to those docs are generated. Linking each occurrence isn't necessary, but all the other references should at least be surrounded by "grave accents" or tickmarks.
-
- This is an example of linking to [can.Component] from another page. If you reference
- `can.Component` later in this section, you don't have to link to it. All subsequent
- references to `can.Component` have grave accents or tickmarks surrounding them.
-
- ### New Section
-
- Another section referencing [can.Component] starts this trend again...
-
-**Note**: The one exception to this is on the module page. When documenting `can.Component` itself, only use the tickmarks, as linking to `can.Component` would just link to the page you are currently modifying.
-
-#### Enclose string literals in tickmarks as they should appear in code
-
-If the developer should type `"@"`, use the tickmarks to make this clear. This avoids the ambiguity of whether the apostrophes or quote marks are part of the text that should be typed. This also applies to any references to variable/key names (e.g., `scope` versus "scope" or **scope**).
-
-#### Include a clear description of your example code
-
-For a developer that's new to CanJS, the description of the example is likely more important than the example itself. Make sure there is a clear description of what the code should accomplish. This includes using all the techniques above. A good description should answer the question, "could you explain what this example code is doing?"
-
-## List of heroes
-
-The following lists everyone who's contributed something to CanJS. If we've forgotten you, please add yourself.
-
-First, thanks to everyone who's contributed to [JavaScriptMVC](https://github.com/bitovi/javascriptmvc/contributors)
-and [jQueryMX](https://github.com/jupiterjs/jquerymx/contributors), and the people at
-[Bitovi](http://bitovi.com/people/). You deserve heaps of recognition as CanJS is direcly based
-off JavaScriptMVC. This page is for contributors after CanJS's launch. Thank you
+## 3.0 Changes
-- [noah](https://github.com/iamnoah)
-([1](https://github.com/canjs/canjs/commit/8193e359cde3b77a44c683ca9f8a5268fc9df44b),
-[2](https://github.com/canjs/canjs/commit/b865588710e7e7dd8a9588ebf8e8c0f4d19fd800),
-[3](https://github.com/canjs/canjs/commit/83a48e7bcb05ed9f179159f540b181db4dcf6e9c),
-[4](https://github.com/Spredfast/canjs/commit/dc7ddd2dc619619f3955c31be1435c6f927b7a35),
-[5](https://github.com/canjs/canjs/pull/214), [6](https://github.com/canjs/canjs/pull/310))
-- [thecountofzero](https://github.com/thecountofzero)
-([1](https://github.com/canjs/canjs/commit/e920434fa53975013688d065ce2e304f225fae75),
-[2](https://github.com/canjs/canjs/commit/8e98186e00b7d6b88869baeb97244877f143034e),
-[3](https://github.com/canjs/canjs/pull/315))
-- [roissard](https://github.com/roissard) ([1](https://github.com/canjs/canjs/commit/44bc72063e429bbc3f8a9a696a3ae4a7e57d12c8),
-[2](https://github.com/canjs/canjs/commit/c711fe05e1cdc99c72df8ac0f415c2ccb536d197))
-- [Michael Kebbekus](https://github.com/makebbekus)
-([1](https://github.com/canjs/canjs/commit/d658d4910e8f3f391e9394449efe2f0c67581dbe))
-- Daniel Salet ([1](https://github.com/canjs/canjs/commit/92487178255360d40b75be49681dc65cbfbf3e18))
-- [Daniel Franz](https://github.com/daniel-franz)
-([1](https://github.com/canjs/canjs/commit/4aae36eea9d671a12f9c459733c48b6fd1e99af4))
-- [trickeyone](https://github.com/trickeyone)
-([1](https://github.com/trickeyone/canjs/commit/2c11f56e0a0511749243055276e3b806984b15fa))
-- [rjgotten](https://github.com/rjgotten)
-([1](https://github.com/canjs/canjs/commit/92c98e7c80d5fd7357eae69a60313d3d06efbdcb))
-- Amy Chen ([1](https://github.com/canjs/canjs/commit/3eee6ba9c69410ac549b909b1c8f860e6d591612))
-- [Max Sadrieh](https://github.com/ms)
-([1](https://github.com/canjs/canjs/commit/06c5a4b3d50d14c5881ee55642fa10f37b71af0b))
-- [dimaf](https://github.com/dimaf)
-([1](https://github.com/canjs/canjs/commit/fc8a4d57c99a280025eb7c613cef92de28c3c160),
-[2](https://github.com/canjs/canjs/pull/145))
-- [yusufsafak](https://github.com/yusufsafak) ([1](https://github.com/canjs/canjs/pull/30))
-- [verto](https://github.com/verto) ([1](https://github.com/canjs/canjs/pull/32))
-- [WearyMonkey](https://github.com/WearyMonkey) ([1](https://github.com/canjs/canjs/issues/27))
-- [cohuman](https://github.com/cohuman)
-([1](https://github.com/canjs/canjs/pull/23), [2](https://github.com/canjs/canjs/pull/26))
-- [roelmonnens](https://twitter.com/roelmonnens)
-- [Craig Wickesser](https://github.com/mindscratch) ([1](https://github.com/canjs/canjs/pull/188))
-- [Jeff Rose](https://github.com/jeffrose) ([1](https://github.com/canjs/canjs/pull/201))
-- [Brad Momberger](https://github.com/bmomberger-reciprocity) ([1](https://github.com/canjs/canjs/pull/292))
-- [Pablo Aguiar](https://github.com/scorphus) ([1](https://github.com/canjs/canjs/pull/303),
-[2](https://github.com/canjs/canjs/pull/313),
-[3](https://github.com/canjs/canjs/pull/317))
-- [David Schovanec](https://github.com/schovi) ([1](https://github.com/canjs/canjs/pull/325),
-[2](https://github.com/canjs/canjs/pull/332))
-- [Dan Connor](https://github.com/onyxrev) ([1](https://github.com/canjs/canjs/pull/284))
-- [Jesse Baird](https://github.com/jebaird) ([1](https://github.com/canjs/canjs/pull/319))
-- [Eric Kryski](https://github.com/ekryski) ([1](https://github.com/canjs/canjs/pull/917))
+In 3.0, nearly every module has its own repository. All code changes should go there. Issues can be submitted to `canjs/canjs`, but once we know the root of the issue, we will move it to a specific repository.
-for helping us with new features, bug fixes, and getting this out the door.
@@ -94,6 +94,7 @@ CanJS including:
- [guides/contributing/documentation Documentation improvements]
- [Create a plugin](https://donejs.com/plugin.html)
- [guides/contributing/evangelism Evangelism - Blog, meetup and conference talks]
+ - [guides/contributing/releases Releases - Maintaining CanJS]
CanJS is managed by the [DoneJS Contributors Team](https://donejs.com/About.html#section=section_Team).
All contributions from all types of contributors are welcome. Contributing
Oops, something went wrong.

0 comments on commit d355260

Please sign in to comment.