From 1e35602683099acc3edff21eb1ff106374779abb Mon Sep 17 00:00:00 2001 From: Chasen Le Hara Date: Fri, 10 Feb 2017 16:44:11 -0800 Subject: [PATCH] Add a contribution guide Fixes #295 --- README.md | 50 +-- code_of_conduct.md | 74 ++++ contributing.md | 27 ++ docs/contribute.md | 178 ---------- docs/guides/contributing.md | 491 +++++++++++++++++++++++++++ docs/guides/guides.md | 4 + docs/theme/static/static.js | 2 +- docs/theme/templates/layout.mustache | 1 + 8 files changed, 599 insertions(+), 228 deletions(-) create mode 100644 code_of_conduct.md create mode 100644 contributing.md delete mode 100644 docs/contribute.md create mode 100644 docs/guides/contributing.md diff --git a/README.md b/README.md index 233490ccf..a6ca56f5e 100644 --- a/README.md +++ b/README.md @@ -30,52 +30,4 @@ DoneJS is a combination of the following technologies: DoneJS is an `npm` package that simply installs all the previous technologies. Check out [DoneJS.com](https://donejs.com/) for the collective [benefits](https://donejs.com/Features.html) of these technologies -and [guides](https://donejs.com/Guides.html) on how to use them together to build an amazing application. - -## Contributing - -### Cloning the repository - -``` -git clone git@github.com:donejs/donejs.git -cd donejs -``` - -### Installing the dependencies - -``` -npm install -``` - -### Running the tests - -``` -npm test -``` - -### Building the docs - -``` -npm run document -``` - -### Deploying to DoneJS.com - -After cloning the repo and installing the dependencies: - -``` -git clone git@github.com:donejs/donejs.git -b gh-pages site/ -``` - -If you get an error saying `Permission denied (publickey)` then you should follow GitHub’s instructions on -[generating an SSH key](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). - -Push a new commit to the `gh-pages` branch with the built docs: - -``` -npm run document -cd site/ -git add --all -git commit -am "Updating site" -git push origin gh-pages -``` +and [guides](https://donejs.com/Guides.html) on how to use them together to build an amazing application. \ No newline at end of file diff --git a/code_of_conduct.md b/code_of_conduct.md new file mode 100644 index 000000000..6a81444f9 --- /dev/null +++ b/code_of_conduct.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at contact@bitovi.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/contributing.md b/contributing.md new file mode 100644 index 000000000..68a868434 --- /dev/null +++ b/contributing.md @@ -0,0 +1,27 @@ +# Contributing to DoneJS + +Check out the [contribution guide on DoneJS.com](https://donejs.com/contributing.html) for information on: + +- Code of Conduct +- Getting Help +- Reporting Bugs +- Suggesting Features +- Project Organization +- Finding Issues +- Developing Locally + - Forking & cloning the repository + - Installing the dependencies + - Making a build + - Running the tests + - Building the documentation +- Changing the Code + - Updating tests + - Updating documentation + - Updating dependencies +- Submitting a Pull Request +- Style Guide +- Publishing & Releasing + - Continuous integration + - Publishing documentation + - Make a release + - Updating DoneJS.com \ No newline at end of file diff --git a/docs/contribute.md b/docs/contribute.md deleted file mode 100644 index a41e720f3..000000000 --- a/docs/contribute.md +++ /dev/null @@ -1,178 +0,0 @@ -@page contribute Contribue to DoneJS -@parent DoneJS -@hide sidebar -@outline 2 ol - -@body -Thank you for contributing to DoneJS! If you need any help setting up a DoneJS development environment and fixing DoneJS bugs, please reach out to us on [gitter](https://gitter.im/donejs/donejs) or email [contact@bitovi.com](mailto:contact@bitovi.com). We will happily walk you through setting up a the environment, creating a test, and submitting a pull request. - -## Reporting Bugs - -To report a bug, please visit [GitHub Issues](https://github.com/donejs/donejs/issues). - -When filing a bug, it is helpful to include: - -- Small examples using tools like [JSFiddle](http://jsfiddle.com/). You can fork the following DoneJS fiddles: - - [jQuery](http://jsfiddle.net/donejs/qYdwR/) - - [Zepto](http://jsfiddle.net/donejs/7Yaxk/) - - [Dojo](http://jsfiddle.net/donejs/9x96n/) - - [YUI](http://jsfiddle.net/donejs/w6m73/) - - [Mootools](http://jsfiddle.net/donejs/mnNJX/) -- 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](https://forums.donejs.com) or talk to us in [gitter](https://gitter.im/donejs/donejs). - -## Installing - -1. Fork DoneJS on GitHub. -2. Clone it with: `git clone git@github.com:/donejs` - -## Structure - -TODO: Explain stack or link to api section. - -## 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 DoneJS repository - `cd /path/to/donejs` -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/donejs/donejs/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. - -## 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 DoneJS.com site locally and regenerate the docs. - -To run the docs and watch the files for changes run the command: -``` -./node_modules/.bin/documentjs -d -f --watch -``` - -Finally, serve the site locally using a tool like [http-server](https://www.npmjs.com/package/http-server). - -## 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 DoneJS 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 DoneJS - `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. - -## Style Guide - -### 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 = "
"; - -### 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 DoneJS: - -#### When referencing another part of DoneJS, 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 DoneJS 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 DoneJS, 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?" diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md new file mode 100644 index 000000000..26c120f3f --- /dev/null +++ b/docs/guides/contributing.md @@ -0,0 +1,491 @@ +@page contributing Contributing +@parent DoneJS +@hide sidebar +@outline 2 ol + +@body +Thank you for your interest in contributing to DoneJS! We welcome all types of contributors, whether you’re interested in helping fix bugs, implementing new features, or answering questions from other community members. + +Contributing to an open source project can be an intimidating experience. We’re committed to making the experience as pleasant and rewarding as possible. + +## Code of Conduct + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +[Please read our Code of Conduct in its entirety before participating in our community.](https://github.com/donejs/donejs/blob/master/code_of_conduct.md) + +## Getting Help + +We’re happy to set up a pairing session to show you how to fix a bug or write a feature. + +If you need any help setting up a DoneJS development environment and fixing DoneJS bugs, please reach out to us on [gitter](https://gitter.im/donejs/donejs) or email [contact@bitovi.com](mailto:contact@bitovi.com). We will happily walk you through setting up a the environment, creating a test, and submitting a pull request. + +If you have any questions, you can always reach us on [Gitter chat](https://gitter.im/canjs/canjs). + +## Reporting Bugs + +To report a bug, please visit [GitHub Issues](https://github.com/donejs/donejs/issues). + +When filing a bug, it is helpful to include: + +- Small examples using tools like [JSFiddle](http://jsfiddle.com/). You can fork the following DoneJS fiddles: + - [jQuery](http://jsfiddle.net/donejs/qYdwR/) + - [Zepto](http://jsfiddle.net/donejs/7Yaxk/) + - [Dojo](http://jsfiddle.net/donejs/9x96n/) + - [YUI](http://jsfiddle.net/donejs/w6m73/) + - [Mootools](http://jsfiddle.net/donejs/mnNJX/) +- 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](https://forums.donejs.com) or talk to us in [gitter](https://gitter.im/donejs/donejs). + +## Suggesting Features + +CanJS uses [GitHub Issues](https://github.com/canjs/canjs/issues/new) to track feature requests. However, +CanJS is made up of many individual GitHub repositories. Ideally, features are created within the +repository whose code needs to be modified. For example, features with +[can-define] can be created at [canjs/can-define/issues/new](https://github.com/canjs/can-define/issues/new). + +If you do not know which repository your feature belongs to, that’s totally ok! Please +create your issue in the main +[canjs/canjs issues page](https://github.com/canjs/canjs/issues/new). The core team will +move the issue to the correct repository if necessary. + +When creating an feature issue, it’s very helpful to include: + + - Examples of what using the feature will look like. + - Benefits and drawbacks of the feature. + - Why the feature is important. + - Any implementation details around the feature. + +Here’s some example well written feature requests: + + - [Make events fire asynchronously and dispatched during request animation frame or setImmediate](https://github.com/canjs/can-event/issues/11) + - [Modify key -> argument behavior in stache](https://github.com/canjs/canjs/issues/1699) + +Also, please search for previous feature requests. If there’s something similar, add to that, or +give it a 👍. + +Finally, if there are any questions, reach out to +us on the [CanJS forums](http://forums.donejs.com/c/canjs) or talk to us on +the [Gitter canjs/canjs channel](https://gitter.im/canjs/canjs). + +## Project Organization + +At its core, DoneJS is a CLI tool that generates an application structure with a number of projects that are built to work together. + +The following projects are a core part of DoneJS: + +- CanJS +- DocumentJS +- FuncUnit +- jQuery++ +- StealJS +- Syn +- Testee + +Here are the DoneJS projects that glue things together: + +- https://github.com/donejs/generator-donejs +- https://github.com/donejs/autorender +- https://github.com/donejs/done-serve +- https://github.com/donejs/cli +- https://github.com/donejs/done-ssr +- https://github.com/donejs/done-ssr-middleware +- https://github.com/donejs/donejs-nw +- https://github.com/donejs/donejs-cordova +- https://github.com/donejs/donejs-documentjs +- https://github.com/donejs/donejs-firebase +- https://github.com/donejs/css +- https://github.com/donejs/done-component +- https://github.com/donejs/donejs-react +- https://github.com/donejs/donejs-electron +- https://github.com/donejs/donejs-feathers +- https://github.com/donejs/deploy +- https://github.com/donejs/donejs-mocha +- https://github.com/donejs/donejs-connect-model +- https://github.com/donejs/donejs-jasmine +- https://github.com/donejs/donejs-vagrant +- https://github.com/donejs/donejs-jshint +- https://github.com/donejs/worker-autorender + +## Finding Issues + +We use the “help wanted” label to mark issues that could be picked up by someone outside the core team. We also use the “easy” label to mark issues that would be good for someone who’s new to contributing to our projects. + +Here are links to GitHub searches for those terms: + +- CanJS + - [easy](https://github.com/search?q=org%3Acanjs+label%3Aeasy&state=open) + - [help wanted](https://github.com/search?q=org%3Acanjs+label%3A%22help+wanted%22&state=open) +- DocumentJS + - [easy](https://github.com/bitovi/documentjs/labels/easy) + - [help wanted](https://github.com/bitovi/documentjs/labels/help%20wanted) +- DoneJS + - [easy](https://github.com/search?q=org%3Adonejs+label%3Aeasy&state=open) + - [help wanted](https://github.com/search?q=org%3Adonejs+label%3A%22help+wanted%22&state=open) +- FuncUnit + - [easy](https://github.com/bitovi/funcunit/labels/easy) + - [help wanted](https://github.com/bitovi/funcunit/labels/help%20wanted) +- jQuery++ + - [easy](https://github.com/bitovi/funcunit/labels/easy) + - [help wanted](https://github.com/bitovi/jquerypp/labels/help%20wanted) +- StealJS + - [easy](https://github.com/search?q=org%3Astealjs+label%3Aeasy&state=open) + - [help wanted](https://github.com/search?q=org%3Astealjs+label%3A%22help+wanted%22&state=open) +- Syn + - [easy](https://github.com/bitovi/syn/labels/easy) + - [help wanted](https://github.com/bitovi/syn/labels/help%20wanted) +- Testee + - [easy](https://github.com/bitovi/syn/labels/easy) + - [help wanted](https://github.com/bitovi/testee/labels/help%20wanted) + +## Developing Locally + +### Forking & cloning the repository + +1. Fork DoneJS on GitHub. +2. Clone it with: `git clone git@github.com:/donejs` + +``` +git clone git@github.com:donejs/donejs.git +cd donejs +``` + +### Installing the dependencies + +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 DoneJS - `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. + + +``` +npm install +``` + + +### 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 DoneJS dev dependencies installed. + +### Running the tests + + +``` +npm test +``` + + +### Building the documentation + + + +``` +npm run document +``` + +## Changing the Code + +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 DoneJS repository - `cd /path/to/donejs` +2. Create a new feature branch - `git checkout -b html5-fix` +3. Make some changes + +### Style guide + +Where possible, our code uses: + +- Tabs not spaces +- JSHint +- CommonJS not ES6 +- jQuery’s [coding conventions](https://contribute.jquery.org/style-guide/js/) + +### Updating tests + +4. Update tests to accommodate your changes +5. Run tests and make sure they pass in all browsers + +### Updating 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 DoneJS.com site locally and regenerate the docs. + +To run the docs and watch the files for changes run the command: +``` +./node_modules/.bin/documentjs -d -f --watch +``` + +Finally, serve the site locally using a tool like [http-server](https://www.npmjs.com/package/http-server). + +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 DoneJS: + +#### When referencing another part of DoneJS, 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 DoneJS 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 DoneJS, 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?" + +### Submitting a Pull Request + +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/donejs/donejs/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. + +## Publishing & Releasing + +### Continuous integration + +#### Travis CI + +All repositories automatically run their tests in [Travis CI](https://travis-ci.org/) using the `npm test` command (browser tests use Firefox as their target browser). If `npm test` is passing locally but not on Travis CI + +- Try setting the `DEBUG=testee*` environment variable in `travis-ci.org/canjs//settings` to get more information. +- Run the tests on an Ubuntu VM (e.g. [Ubuntu for Virtualbox](https://www.virtualbox.org/wiki/Linux_Downloads)) + +#### Saucelabs + +[canjs/canjs](https://github.com/canjs/canjs) also runs the tests of all dependencies in the supported browsers on [Saucelabs](https://saucelabs.com): + +[![Sauce Test Status](https://saucelabs.com/browser-matrix/canjs.svg)](https://saucelabs.com/u/canjs) + +To view Saucelabs test runs and results, request an invite from a Saucelabs user that has access to the `canjs` Saucelabs project (existing users can send invites under [my account](https://saucelabs.com/beta/users/canjs)). Saucelabs tests can be run locally via + +``` +npm run ci +``` + +#### Updating dependencies + +All CanJS repositories are set up with [Greenkeeper](https://greenkeeper.io/). Greenkeeper tracks dependencies and creates a branch for every new version coming in. This will trigger Travis CI to run the tests and if a dependency update breaks the tests or a breaking (major) version was released, it will create a pull request. + +Greenkeeper is free for open source projects and works on the CanJS organization level. To add a new project or change the status of an existing project: + +- Install the command line via `npm install greenkeeper -g` +- Run `greenkeeper login` to log in via GitHub +- For more information run `greenkeeper` or `greenkeeper start` +- To enable a project, in the project folder run `greenkeeper enable` + +### Publishing documentation + +Once the docs look right locally, commit your changes, then run: + +``` +> make +``` + +The make script will generate the documentation again and push out the `gh-pages` branch. + +### Make a release + +With the exception of the `can` package, __ALL subprojects__ MUST follow the [Semantic Versioning](http://semver.org/) guidelines in the form of `MAJOR.MINOR.PATCH` for + +- `MAJOR` version when you make incompatible API changes, +- `MINOR` version when you add functionality in a backwards-compatible manner, and +- `PATCH` version when you make backwards-compatible bug fixes. + +Before making any release please make sure that + +- You have write access to the GitHub repository you want to publish. +- Have an [npm](https://www.npmjs.com) account and are logged in on the CLI tool (`npm whoami`). +- Your user is a collaborator on npm. You can ask an existing collaborator to add you. Existing collaborators can be listed via `npm owner ls ` or on the npm module page (e.g. [can-route](https://www.npmjs.com/package/can-route)). + + +#### Releasing CanJS subprojects + +All CanJS subprojects modules have the same structure which allows making releases through NPM scripts. + +To make a release: + +1. Move to the `master` branch +2. Fetch all latest changes from the repository +3. Reinstall all Node modules in their latest version + + ``` + git checkout master + git fetch --all && git rebase + npm cache clean + rm -rf node_modules + npm install + ``` + +4. Then run `npm run release:`. For example, to make a `PATCH` release: + + ``` + npm run release:patch + ``` + +This will run the tests, build, bump the version number accordingly and publish the module to [npm](https://www.npmjs.com/). + + +#### Releasing the CanJS main project + +The CanJS main project repository is at +[canjs/canjs](https://github.com/canjs/canjs) and published as the `can` package. We +publish a `can` module so there is a specified version of the library packages that are +__integration tested__ to work together. A single `can` release can include multiple +releases of library packages. + +The `can` package does __not__ follow strict [semantic versioning](http://semver.org/) +guidelines. It still follows a `MAJOR.MINOR.PATCH` release names, but where: + + - `MAJOR` - Incompatible API changes in a library in the [can-core] or [can-infrastructure] collection. + - `MINOR` - Either: + - New features added [can-core] and [can-infrastructure] but still backwards-compatible. + - New [can-ecosystem] or [can-legacy] library added or removed to their respective collection. + - `PATCH` - Either: + - Bug fixes in [can-core] and [can-infrastructure]. + - A new release of a [can-ecosystem] or [can-legacy] library. + +The `can` package __does__ follow strict [semantic versioning](http://semver.org/) guidelines +with respect to the [can-core] and [can-infrastructure] collections. If a +new [can-ecosystem] or [can-legacy] package is added to `can`, it’s treated as a `MINOR` changes to `can`, +any subsequent releases of those packages are treated as `PATCH` changes to `can`. + +When making a release, review the the version number changes and collection of all packages that have changed within the release. Then run `npm run release:`. + +For example, the following would be a `PATCH` release: + +``` +can-core-a 3.0.1 -> 3.0.2 +can-core-b 3.0.1 -> 3.0.10 +can-ecosystem-a 1.0.0 -> 2.0.0 +``` + +The following would be a `MINOR` release: + +``` +can-core-a 3.0.1 -> 3.0.2 +can-core-b 3.0.1 -> 3.0.10 +// this means can-ecoystem-b was added to the ecosystem collection ++ can-ecosystem-b 0.0.1 +``` + +The following would be a `MINOR` release: + +``` +can-core-a 3.0.1 -> 3.0.2 +can-core-b 3.0.1 -> 3.1.0 +can-ecosystem-a 1.0.0 -> 1.0.1 +``` + +The following would be a `MAJOR` release: + +``` +can-core-a 3.0.1 -> 3.0.2 +can-core-b 3.0.1 -> 3.1.0 +can-infrastructure-a 3.0.1 -> 4.0.0 +``` + +### Updating DoneJS.com + +After cloning the repo and installing the dependencies: + +``` +git clone git@github.com:donejs/donejs.git -b gh-pages site/ +``` + +If you get an error saying `Permission denied (publickey)` then you should follow GitHub’s instructions on +[generating an SSH key](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). + +Push a new commit to the `gh-pages` branch with the built docs: + +``` +npm run document +cd site/ +git add --all +git commit -am "Updating site" +git push origin gh-pages +``` + +canjs.com is hosted on [GitHub pages](https://pages.github.com/) from the [canjs/canjs#gh-pages](https://github.com/canjs/canjs/tree/gh-pages) branch. To generate and push a new version of the website, verify you have push access to that branch. Then get all latest changes via: + +``` +git checkout master +git fetch --all && git rebase +npm cache clean +rm -rf node_modules +npm install +``` + +We also have to delete the local `gh-pages` branch: + +``` +git branch -D gh-pages +``` + +Then run + +``` +make +``` + +This will generate and publish a new version of the website. + +## Evangelism + +Hopefully you love CanJS as much as we do and you want to share your +knowledge about it. Fantastic! We can help you. + +There’s lots of ways to spread the word about CanJS such as: + + - Giving a presentation at a conference or meetup + - Organizing or speaking at a CanJS or DoneJS meetup + - Writing a blog article + +Whatever you do, please let us know so we can promote you and what you’re doing. + +### Giving a presentation + +The [Presentations Google Drive Folder](https://drive.google.com/drive/u/1/folders/0Bx-kNqf-wxZeaWc2ay1ZSzZZQXc) +contains all of the DoneJS teams talks organized by project. It contains +a CanJS folder with CanJS presentations. + +Some of the presentations are out dated, but it’s a good place to check for +existing content. + +### Meetups + +There are several DoneJS meetups already created: + + - [Chicago](http://www.meetup.com/DoneJS-Chicago/) + - [Silicon Valley](http://www.meetup.com/DoneJS-Silicon-Valley/) + - [Boston](http://www.meetup.com/DoneJS-Boston/) + - [Ft. Lauderdale](http://www.meetup.com/DoneJS-Fort-Lauderdale/) + - [Los Angeles](http://www.meetup.com/DoneJS-LA/) + - [New York](http://www.meetup.com/DoneJS-NYC/) + - [Phoenix](http://www.meetup.com/DoneJS-Phoenix/) + - [Raleigh-Durham](http://www.meetup.com/DoneJS-raleigh-durham/) + - [San Francisco](http://www.meetup.com/DoneJS-San-Francisco/) + - [Seattle](http://www.meetup.com/DoneJS-Seattle/) + +We’re always looking for people to speak at one of these meetups, become an organizer, +or start their own meetup. If you are interested in any of these things, +please let Justin Meyer know (`justin@bitovi.com`). + +### Writing a blog article + +If you’re writing something about CanJS and would like us to review it, +we’re happy to help. Once it’s published, let us know so we can promote it. \ No newline at end of file diff --git a/docs/guides/guides.md b/docs/guides/guides.md index 76cb2bccd..2dcee56db 100644 --- a/docs/guides/guides.md +++ b/docs/guides/guides.md @@ -61,3 +61,7 @@ Specifically, this guide will walk through the implementation of the following b - Handling relationships between model types. - Setup node services and server-side rendering on the same process. - How to turn off parts of the app that should not be server-side rendered. + +## [Contributing](/contributing.html) + +The contribution guide includes information about our code of conduct, reporting bugs, submitting new code, and more! diff --git a/docs/theme/static/static.js b/docs/theme/static/static.js index 62b282cf9..74eb297cf 100644 --- a/docs/theme/static/static.js +++ b/docs/theme/static/static.js @@ -231,7 +231,7 @@ steal( var scrollSpyCurrentH2 = $( "#scrollSpyCurrentH2" ); var scrollSpyCurrentH3 = $( "#scrollSpyCurrentH3" ); var activeH2Li = $(); - var doJQCollapsing = $( "body.Guide, body.place-my-order, body.Apis" ).length ? true : false; + var doJQCollapsing = $( "body.Guide, body.place-my-order, body.Apis, body.contributing" ).length ? true : false; if ( doJQCollapsing ) { $( "section.contents ol ol" ).hide(); diff --git a/docs/theme/templates/layout.mustache b/docs/theme/templates/layout.mustache index 1f51a2ae0..aeec39357 100644 --- a/docs/theme/templates/layout.mustache +++ b/docs/theme/templates/layout.mustache @@ -91,6 +91,7 @@
  • Creating a plugin
  • Creating a generator
  • Example App: Bitballs
    • +
  • Contributing