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..48d75cacc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing to DoneJS + +Check out the [contribution guide on DoneJS.com](https://donejs.com/contributing.html) for information on: + +- [Code of Conduct](https://donejs.com/contributing.html#section=section_CodeofConduct) +- [Getting Help](https://donejs.com/contributing.html#section=section_GettingHelp) +- [Project Organization](https://donejs.com/contributing.html#section=section_ProjectOrganization) +- [Reporting Bugs](https://donejs.com/contributing.html#section=section_ReportingBugs) +- [Suggesting Features](https://donejs.com/contributing.html#section=section_SuggestingFeatures) +- [Finding Ways to Contribute](https://donejs.com/contributing.html#section=section_FindingWaystoContribute) + - [Finding open issues](#section=section_Findingopenissues) + - [Getting involved in the community](#section=section_Gettinginvolvedinthecommunity) + - [Spreading the word](#section=section_Spreadingtheword) +- [Developing Locally](https://donejs.com/contributing.html#section=section_DevelopingLocally) + - [Signing up for GitHub](https://donejs.com/contributing.html#section=section_SigningupforGitHub) + - [Forking & cloning the repository](https://donejs.com/contributing.html#section=section_Forking_cloningtherepository) + - [Installing the dependencies](https://donejs.com/contributing.html#section=section_Installingthedependencies) + - [Running the tests](https://donejs.com/contributing.html#section=section_Runningthetests) + - [Building the documentation](https://donejs.com/contributing.html#section=section_Buildingthedocumentation) + - [Viewing the site](https://donejs.com/contributing.html#section=section_Viewingthesite) +- [Changing the Code](https://donejs.com/contributing.html#section=section_ChangingtheCode) + - [Creating a new branch](https://donejs.com/contributing.html#section=section_Creatinganewbranch) + - [Style guide](https://donejs.com/contributing.html#section=section_Styleguide) + - [Updating the tests](https://donejs.com/contributing.html#section=section_Updatingtests) + - [Updating the documentation](https://donejs.com/contributing.html#section=section_Updatingthedocumentation) + - [Submitting a pull request](https://donejs.com/contributing.html#section=section_Submittingapullrequest) +- [Updating DoneJS.com](https://donejs.com/contributing.html#section=section_UpdatingDoneJS_com) +- [Evangelism](https://donejs.com/contributing.html#section=section_Evangelism) + - [Writing a blog article](https://donejs.com/contributing.html#section=section_Writingablogarticle) + - [Speaking at a conference or meetup](https://donejs.com/contributing.html#section=section_Speakingataconferenceormeetup) + - [Organizing a DoneJS meetup](https://donejs.com/contributing.html#section=section_OrganizingaDoneJSmeetup) \ No newline at end of file diff --git a/README.md b/README.md index 6bb892908..6e545a3a8 100644 --- a/README.md +++ b/README.md @@ -34,48 +34,4 @@ and [guides](https://donejs.com/Guides.html) on how to use them together to buil ## 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 -``` +Check out the [contribution guide on DoneJS.com](https://donejs.com/contributing.html). \ 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..05418dd07 --- /dev/null +++ b/docs/guides/contributing.md @@ -0,0 +1,429 @@ +@page contributing Contributing +@parent DoneJS +@hide sidebar +@outline 2 ol + +@body +Thank you for your interest in contributing to DoneJS! DoneJS is maintained by [the core team](./About.html#section=section_Team) but depends on contributors like you! Whether you’re interested in [fixing issues](#section=section_Findingopenissues), [answering questions](#section=section_Gettinginvolvedinthecommunity), or [spreading the word](#section=section_Evangelism), we welcome you to our community! + +Contributing to an open source project can be an intimidating experience. We’re committed to making it as pleasant and rewarding as possible. Please always feel free to [reach out to us on Gitter](https://gitter.im/donejs/donejs). + +## Code of Conduct + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and 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 + +[Our forums](http://forums.donejs.com/) and [Gitter chat](https://gitter.im/donejs/donejs) are the best places to ask questions. The core team regularly checks both and there are other users who generously help others. + +If you’re interested in contributing to DoneJS, the core team is happy to pair with you to fix a bug or write a new feature! Please either message us on Gitter or the forums, or leave a comment on the GitHub issue you’re interested in helping with. We will happily walk you through setting up your development environment, creating a test and/or writing documentation, and submitting a pull request. + +## 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](https://canjs.com/) +- [DocumentJS](https://documentjs.com/) +- [FuncUnit](https://funcunit.com/) +- [jQuery++](http://jquerypp.com/) +- [StealJS](https://stealjs.com/) +- [Syn](https://github.com/bitovi/syn) +- [Testee](https://github.com/bitovi/testee) + +Here are the DoneJS projects that glue things together and add additional functionality: + +- [autorender](https://github.com/donejs/autorender) +- [cli](https://github.com/donejs/cli) +- [css](https://github.com/donejs/css) +- [deploy](https://github.com/donejs/deploy) +- [component](https://github.com/donejs/done-component) +- [done-serve](https://github.com/donejs/done-serve) +- [done-ssr](https://github.com/donejs/done-ssr) +- [done-ssr-middleware](https://github.com/donejs/done-ssr-middleware) +- [donejs](https://github.com/donejs/donejs) +- [donejs-connect-model](https://github.com/donejs/donejs-connect-model) +- [donejs-cordova](https://github.com/donejs/donejs-cordova) +- [donejs-documentjs](https://github.com/donejs/donejs-documentjs) +- [donejs-electron](https://github.com/donejs/donejs-electron) +- [donejs-feathers](https://github.com/donejs/donejs-feathers) +- [donejs-firebase](https://github.com/donejs/donejs-firebase) +- [donejs-jasmine](https://github.com/donejs/donejs-jasmine) +- [donejs-jshint](https://github.com/donejs/donejs-jshint) +- [donejs-mocha](https://github.com/donejs/donejs-mocha) +- [donejs-nw](https://github.com/donejs/donejs-nw) +- [donejs-react](https://github.com/donejs/donejs-react) +- [donejs-vagrant](https://github.com/donejs/donejs-vagrant) +- [generator-donejs](https://github.com/donejs/generator-donejs) +- [worker-autorender](https://github.com/donejs/worker-autorender) + +## Reporting Bugs + +DoneJS uses [GitHub Issues](https://github.com/donejs/donejs/issues) to track bugs. As noted [above](#section=section_ProjectOrganization), DoneJS is made up of many individual GitHub repositories. Ideally, bugs are created within the +repository whose code is causing the issue. For example, if you’re having issues with the development server, you can create an issue at [donejs/done-serve/issues/new](https://github.com/donejs/done-serve/issues/new?labels=bug). + +If you do not know which repository your issue belongs to, that’s okay! Please +create your issue in +[the main DoneJS repo](https://github.com/donejs/donejs/issues/new?labels=bug). The core team will +move the issue to the correct repository (if necessary). + +When creating an issue, it’s helpful to include: + +- How often you can reproduce it. +- A detailed description of the issue with specific details to help us understand the problem. +- A list of the steps to reproduce the issue. +- What actually happened versus what you expected to have happen. +- Details about your environment, including the version of DoneJS, Node.js, and npm you’re using. + +Before filing a new issue, please search for previous tickets. If there’s something similar, add to that, or +give it a 👍. If you can provide additional information that’s not already in the issue, please add a comment to it. + +If you are unsure about any of this or have any other questions, please reach out to +us on the [DoneJS forums](http://forums.donejs.com/c/donejs) or talk to us on +the [Gitter donejs/donejs channel](https://gitter.im/donejs/donejs). We’re happy to discuss any bugs and help you file a bug report. + +## Suggesting Features + +DoneJS uses [GitHub Issues](https://github.com/donejs/donejs/issues) to track feature suggestions. As noted [above](#section=section_ProjectOrganization), DoneJS is made up of many individual GitHub repositories. Ideally, feature suggestions are created within the +repository whose code could be improved. For example, if you have a suggestion related to the development server, you can create an issue at [donejs/done-serve/issues/new](https://github.com/donejs/done-serve/issues/new?labels=enhancement). + +If you do not know which repository your issue belongs to, that’s okay! Please +create your issue in +[the main DoneJS repo](https://github.com/donejs/donejs/issues/new?labels=enhancement). The core team will +move the issue to the correct repository (if necessary). + +When filing a feature suggestion, 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. + +Before filing a new suggestion, please search for previous feature requests. If there’s something similar, add to that, or +give it a 👍. If you have additional ideas that are not already in the issue, please add a comment to it. + +If you are unsure about any of this or have any other questions, please reach out to +us on the [DoneJS forums](http://forums.donejs.com/c/donejs) or talk to us on +the [Gitter donejs/donejs channel](https://gitter.im/donejs/donejs). We’re happy to discuss any ideas and help you file a feature suggestion. + +## Finding Ways to Contribute + +There are many ways to contribute to DoneJS, whether you’re a developer who wants to code, a designer who can help improve the design and usability of our projects, or someone who’s interested in helping other members of the community. + +### Finding open issues + +DoneJS uses [GitHub Issues](https://github.com/donejs/donejs/issues) to track improvements we want to make to the project, whether that’s bug fixes, new features, design improvements, etc. + +We use a few labels to organize issues across all of the repositories: + +- “help wanted” for any issues with which the core team would like help +- “easy” for issues the core team thinks are good for someone who’s new to contributing +- “documentation” for issues related to documenting the APIs +- “design” for issues that could use a designer’s expertise + +Here are links to GitHub searches for those terms: + +- CanJS + - [design](https://github.com/search?q=org%3Acanjs+label%3Adesign&state=open) + - [documentation](https://github.com/search?q=org%3Acanjs+label%3Adesign&state=open) + - [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 + - [design](https://github.com/bitovi/documentjs/labels/design) + - [documentation](https://github.com/bitovi/documentjs/labels/documentation) + - [easy](https://github.com/bitovi/documentjs/labels/easy) + - [help wanted](https://github.com/bitovi/documentjs/labels/help%20wanted) +- DoneJS + - [design](https://github.com/search?q=org%3Adonejs+label%3Adesign&state=open) + - [documentation](https://github.com/search?q=org%3Adonejs+label%3Adocumentation&state=open) + - [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 + - [design](https://github.com/bitovi/funcunit/labels/design) + - [documentation](https://github.com/bitovi/funcunit/labels/documentation) + - [easy](https://github.com/bitovi/funcunit/labels/easy) + - [help wanted](https://github.com/bitovi/funcunit/labels/help%20wanted) +- jQuery++ + - [design](https://github.com/bitovi/funcunit/labels/design) + - [documentation](https://github.com/bitovi/funcunit/labels/documentation) + - [easy](https://github.com/bitovi/funcunit/labels/easy) + - [help wanted](https://github.com/bitovi/jquerypp/labels/help%20wanted) +- StealJS + - [design](https://github.com/search?q=org%3Astealjs+label%3Adesign&state=open) + - [documentation](https://github.com/search?q=org%3Astealjs+label%3Adocumentation&state=open) + - [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 + - [design](https://github.com/bitovi/syn/labels/design) + - [documentation](https://github.com/bitovi/syn/labels/documentation) + - [easy](https://github.com/bitovi/syn/labels/easy) + - [help wanted](https://github.com/bitovi/syn/labels/help%20wanted) +- Testee + - [design](https://github.com/bitovi/syn/labels/design) + - [documentation](https://github.com/bitovi/syn/labels/documentation) + - [easy](https://github.com/bitovi/syn/labels/easy) + - [help wanted](https://github.com/bitovi/testee/labels/help%20wanted) + +### Getting involved in the community + +You can also get involved in our community by posting in our forums, chatting with us on Gitter, and answering questions on Stack Overflow. + +- CanJS + - [Forums](http://forums.donejs.com/c/canjs) + - [Gitter](https://gitter.im/canjs/canjs) + - [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=canjs+answers:0) +- DocumentJS + - [Forums](http://forums.donejs.com/c/documentjs) + - [Gitter](https://gitter.im/bitovi/documentjs) + - [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=documentjs+answers:0) +- DoneJS + - [Forums](http://forums.donejs.com/c/donejs) + - [Gitter](https://gitter.im/donejs/donejs) + - [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=donejs+answers:0) +- FuncUnit + - [Gitter](https://gitter.im/bitovi/funcunit) + - [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=funcunit+answers:0) +- jQuery++ + - [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=jquerypp+answers:0) +- StealJS + - [Forums](http://forums.donejs.com/c/stealjs) + - [Gitter](https://gitter.im/stealjs/steal) + - [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=stealjs+answers:0) +- Syn + - [Gitter](https://gitter.im/bitovi/syn) +- Testee + - [Gitter](https://gitter.im/bitovi/testee) + +### Spreading the word + +We also always need help spreading the word about the DoneJS projects. Check out the [evangelism section](#section=section_Evangelism) on how you can [write a blog post](#section=section_Writingablogarticle), [speak at a conference](#section=section_Speakingataconferenceormeetup), or [organize a meetup](#section=section_OrganizingaDoneJSmeetup). + +## Developing Locally + +This section will walk you through setting up the [main DoneJS repository](https://github.com/donejs/donejs) on your computer. Remember that DoneJS is [split into multiple repositories](#section=section_ProjectOrganization), but you can apply the same general steps to set up any of the other repos. + +### Signing up for GitHub + +If you don’t already have a GitHub account, you’ll need to [create a new one](https://help.github.com/articles/signing-up-for-a-new-github-account/). + +### Forking & cloning the repository + +A “fork” is a copy of a repository in your personal GitHub account. “Cloning” is the process of getting the repository’s source code on your computer. + +GitHub has a guide for [forking a repo](https://help.github.com/articles/fork-a-repo/). To fork DoneJS, you can start by going to its [fork page](https://github.com/donejs/donejs/fork). + +Next, you’ll want to clone the repo. [GitHub’s cloning guide](https://help.github.com/articles/cloning-a-repository/) explains how to do this on Linux, Mac, or Windows. + +GitHub’s guide will [instruct you](https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork) to clone it with a command like: + +```shell +git clone https://github.com/YOUR-USERNAME/donejs +``` + +Make sure you replace `YOUR-USERNAME` with your GitHub username. + +### Installing the dependencies + +After you’ve [forked & cloned the repository](#section=section_Forking_cloningtherepository), you’ll need to install the project’s dependencies. + +First, make sure you’ve [installed Node.js and npm](https://docs.npmjs.com/getting-started/installing-node). + +If you just cloned the repo from the command line, you’ll want to switch to the folder with your clone: + +```shell +cd donejs +``` + +Next, install the project’s dependencies with npm: + +```shell +npm install +``` + +### Running the tests + +Firefox is used to run the repository’s tests. If you don’t already have it, [download Firefox](https://www.mozilla.org/en-US/firefox/new/). Mozilla has guides for installing it on [Linux](https://support.mozilla.org/t5/Install-and-Update/Install-Firefox-on-Linux/ta-p/2516), [Mac](https://support.mozilla.org/t5/Install-and-Update/How-to-download-and-install-Firefox-on-Mac/ta-p/3453), and [Windows](https://support.mozilla.org/t5/Install-and-Update/How-to-download-and-install-Firefox-on-Windows/ta-p/2210). + +After Firefox is installed, you can run: + +```shell +npm test +``` + +If every test passed, congratulations! You have everything you need to change the code and have the core team review it. + +### Building the documentation + +The [main DoneJS repo](https://github.com/donejs/donejs) contains [DoneJS.com](https://donejs.com/). + +To build the site, run: + +```shell +npm run document +``` + +[`npm run`](https://docs.npmjs.com/cli/run-script) will look for the `document` script in the repository’s [`package.json`](https://github.com/donejs/donejs/blob/master/package.json) and run it. + +### Viewing the site + +After you [build the docs](#section=section_Buildingthedocumentation), your `donejs` repository will contain a `site` folder with the website. + +To view the site, we recommend you install [http-server](https://www.npmjs.com/package/http-server). + +```shell +npm install http-server -g +``` + +After it’s installed, you can start a server for the `site` directory: + +```shell +http-server site +``` + +`http-server` will tell you where you can go in your browser to see the site. It will be something like [http://127.0.0.1:8080]. + +## Changing the Code + +Now that your computer is set up to [develop DoneJS locally](#section=section_DevelopingLocally), you can make changes in your local repository. + +The DoneJS projects generally follow the [GitHub flow](https://help.github.com/articles/github-flow/). This section will briefly explain how you can make changes on your computer and submit a pull request to have those changes merged into the main project. + +### Creating a new branch + +Starting in the DoneJS repository you have cloned to your computer, you can create a new branch: + +```shell +git checkout -b your-branch-name +``` + +Replace `your-branch-name` with the name of your feature branch. You can name the feature branch whatever you’d like. We recommend starting the name with the issue number and a few words related to the issue. For example, for [#295 “Make a contribution guide”](https://github.com/donejs/donejs/issues/295), `295-contribution-guide` is an appropriate branch name. + +### Style guide + +Where possible, our code generally follows [jQuery’s coding conventions](https://contribute.jquery.org/style-guide/js/). + +### Updating tests + +The [`test` directory](https://github.com/donejs/donejs/tree/master/test) contains files related to testing the code in the repository. When fixing bugs or writing new features, you should update the existing tests or create new tests to cover your changes. + +After updating the tests, make sure you [run the tests](#section=section_Runningthetests). + +### Updating the documentation + +The [`docs`](https://github.com/donejs/donejs/tree/master/docs) and [`guides`](https://github.com/donejs/donejs/tree/master/guides) directories contain the files used to generate [DoneJS.com](https://donejs.com/). + +After making changes, make sure you [build the documentation](#section=section_Buildingthedocumentation). + +### Submitting a pull request + +Once you’ve made your changes and [run the tests](#section=section_Runningthetests), you can push your branch to GitHub: + +```shell +git push origin your-branch-name +``` + +Make sure you replace `your-branch-name` with the name of your branch. + +Next, go to the DoneJS repository’s [compare changes](https://github.com/donejs/donejs/compare) page and click on “compare across forks.” You’ll need to change the “head fork” to your repository and select your branch name. + +After you’ve selected your forked repository and branch, you can click on “Create pull request”. Give your PR a meaningful title and provide details about the change in the description, including a link to the issue(s) your PR addresses. If applicable, please include a screenshot or gif to demonstrate your change. This makes it easier for reviewers to verify that it works for them. [LICEcap](http://www.cockos.com/licecap/) is a great tool for making gifs. + +Once you’ve filled out your pull request’s details, click on “Create pull request”. The core team will receive a notification about your pull request and will provide feedback. + +GitHub has additional documentation on [creating a pull request from a fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) that you might find useful. + +## Updating DoneJS.com + +First, create a new clone and install the dependencies: + +```shell +git clone git@github.com:donejs/donejs.git -b gh-pages site/ +npm install +``` + +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: + +```shell +npm run document +cd site/ +git add --all +git commit -am "Updating the site" +git push origin gh-pages +``` + +[DoneJS.com](https://donejs.com/) is hosted on [GitHub pages](https://pages.github.com/) from the [`gh-pages`](https://github.com/donejs/donejs/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: + +```shell +git checkout master +git fetch --all && git rebase +``` + +Then, reinstall the dependencies: + +```shell +npm cache clean +rm -rf node_modules +npm install +``` + +Next, delete the local `gh-pages` branch: + +```shell +git branch -D gh-pages +``` + +Then run the following to generate and publish a new version of the website: + +```shell +make +``` + +## Evangelism + +Hopefully you love DoneJS as much as we do and you want to share your +knowledge about it. Fantastic! We want to help you. + +There are lots of ways to spread the word about DoneJS, including: + + - Writing a blog article + - Speaking at a conference or meetup + - Organizing a DoneJS meetup + +No matter what you’re interested in, please [email Chasen Le Hara](mailto:chasen@bitovi.com) so he can help promote you and what you’re doing. + +### Writing a blog article + +If you’re writing something about DoneJS and would like the core team to review it, +we’re happy to help. Once it’s published, let us know so we can promote it. + +### Speaking at a conference or meetup + +The [presentations list](./presentations.html) contains a variety of talks related to the DoneJS projects. + +### Organizing a DoneJS meetup + +There are several local DoneJS groups: + + - [Boston](https://www.meetup.com/DoneJS-Boston/) + - [Chicago](https://www.meetup.com/DoneJS-Chicago/) + - [Ft. Lauderdale](https://www.meetup.com/DoneJS-Fort-Lauderdale/) + - [Los Angeles](https://www.meetup.com/DoneJS-LA/) + - [New York](https://www.meetup.com/DoneJS-NYC/) + - [Phoenix](https://www.meetup.com/DoneJS-Phoenix/) + - [Raleigh-Durham](https://www.meetup.com/DoneJS-raleigh-durham/) + - [San Francisco](https://www.meetup.com/DoneJS-San-Francisco/) + - [Seattle](https://www.meetup.com/DoneJS-Seattle/) + - [Silicon Valley](https://www.meetup.com/DoneJS-Silicon-Valley/) + +We’re always looking for people to speak at one of these groups, become an organizer, +or start their own group. If you are interested in any of these things, +please let us know! \ No newline at end of file diff --git a/docs/guides/guides.md b/docs/guides/guides.md index 76cb2bccd..c742a43e0 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](./contributing.html) includes information about our code of conduct, reporting bugs, submitting new code, and more! \ No newline at end of file diff --git a/docs/guides/presentations.md b/docs/guides/presentations.md new file mode 100644 index 000000000..7a746347b --- /dev/null +++ b/docs/guides/presentations.md @@ -0,0 +1,212 @@ +@page presentations Presentations +@parent DoneJS +@hide sidebar +@outline 1 ol + +@body +The following talks & trainings are available in the [Presentations folder on Google Drive](https://drive.google.com/open?id=0Bx-kNqf-wxZeaWc2ay1ZSzZZQXc). + +Some of the presentations are complete and have been used before; others are a work in progress. Please [email Chasen Le Hara](mailto:chasen@bitovi.com) if you plan on developing or improving a presentation. + +If you make changes to one of the presentations, please bring it to the top of the list so it’s sorted by most recently updated presentations. + +## Full List + +### Dynamic Animations with Declarative Templates + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEek5SZFRzdy00Mk0) +- Last Modified: 2017-02-01 + +### StealJS Training + +- [Download](https://drive.google.com/open?id=0B09kZkWwiRDvNGZZTWx1Z0tqZUk) +- Last Modified: 2017-02-01 + +### Lightning-Fast DOM Updates with CanJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEb244MkRjdEs4d1U) +- Last Modified: 2017-01-31 + +### Easy Module Loading with StealJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEcVdyUGNFZ2xNSEk) +- [Download](https://drive.google.com/open?id=0B09kZkWwiRDvUkU5aW5RZnJtT2s) +- Last Modified: 2017-01-31 + +### Preparing for the Future of JavaScript + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEeTNGdkNuR2k0YzQ) +- Last Modified: 2017-01-30 + +### Server-Side Rendering Ain’t Easy + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFENDFqV3JyWWdSNzA) +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZed3pDNHprbFppc2s) +- Last Modified: 2017-01-18 + +### Writing Plugins: The On-Ramp to Modern JavaScript + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEdDdWT29sX1BibHc) +- Last Modified: 2017-01-19 + +### Real-Time with CanJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEN21ESzVLVXphLWs) +- Last Modified: 2017-01-18 + +### Object-Oriented and Functional Programming with CanJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEc1J0cTRXYVY2U0U) +- Last Modified: 2017-01-18 + +### Federated State with CanJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEOXNCeWxBWHYyazA) +- Last Modified: 2017-01-18 + +### MVVM Separation of Concerns with CanJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFESnB4U1VJTkxOSFE) +- Last Modified: 2017-01-18 + +### Module Loaders: Master the Pipeline + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEYURlQl95eGprWnM) +- Last Modified: 2017-01-18 + +### Using can-connect with Angular 2 + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFERDdKckZOTTcyc00) +- Last Modified: 2017-01-18 + +### Building Progressive Web Apps with DoneJS + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEZGJnU1Ezd3A0SG8) +- Last Modified: 2017-01-18 + +### Does your DI framework belong in JS? + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEekhNVWhXOGl6aDg) +- Last Modified: 2017-01-18 + +### How DDD & TDD Saved My Bacon + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEdnZRSXdBR2hELUE) +- Last Modified: 2017-01-18 + +### Your Framework Won’t Save You + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEeEdEUGtVNWh6Tlk) +- Last Modified: 2017-01-17 + +### The Modlet Pattern: A Better Way to Organize Your Front-End Code + +- [Description](https://drive.google.com/open?id=0B8wssyNpvaFEUU9aYnpVNTN1Z2c) +- [Download](https://drive.google.com/open?id=0BwYNuFd8LhXyWFNnN2xmMGZMaG8) +- Last Modified: 2017-01-04 + +### Getting can-set and real-time to work + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeQTF5WE5OTU9mZlk) +- Last Modified: 2016-12-14 + +### TodoMVC Intro to CanJS + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeVEoxeXRMZHIweE0) +- Last Modified: 2016-11-22 + +### Bitballs + +- [Download](https://drive.google.com/open?id=0Bx1SymulhNqNUE94VE9RSTNyaXc) +- Last Modified: 2016-11-16 + +### can-define-stream + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeazU3NUN5aGxTTVU) +- Last Modified: 2016-10-26 + +### can-define + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeaXdJNUJBYi01T0k) +- Last Modified: 2016-08-22 + +### DoneJS Place My Order + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeT2pJUnh3RTZZclk) +- Last Modified: 2016-07-29 + +### High Performance Apps with DoneJS + +- [Download](https://drive.google.com/open?id=0B8wssyNpvaFEODNwbk05TXVMLTQ) +- [Download](https://drive.google.com/open?id=0B8wssyNpvaFEdXZqNF96RjkyYmM) +- Last Modified: 2016-07-09 + +### EZPZ ES6 (StealJS Quick Start) + +- [Download](https://drive.google.com/open?id=0BwsllsHQy1SdYm1BMmxjbzFuUEE) +- Last Modified: 2016-06-07 + +### Worker Thread Rendering + +- [Download](https://drive.google.com/open?id=0B09kZkWwiRDvc2NLV05QME10UVU) +- Last Modified: 2016-05-16 + +### Comprehensive Testing + +- [Download](https://drive.google.com/open?id=0B8wssyNpvaFENDh2UkZ2WnVpdTA) +- Last Modified: 2016-05-13 + +### DoneJS Generators + +- [Download](https://drive.google.com/open?id=0B9Ygfgud0btpdExjT0R3TUtXZ00) +- Last Modified: 2016-05-13 + +### Desktop & Mobile Builds with DoneJS + +- [Download](https://drive.google.com/open?id=0B8wssyNpvaFEVXF3cmNWWlZxRTQ) +- Last Modified: 2016-05-12 + +### Overview of can-fixture + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeeHc5SjdfczNnN3M) +- Last Modified: 2016-04-26 + +### can-map-define + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeS1BRX3JuaFc0dVk) +- Last Modified: 2016-04-12 + +### Continuous Integration Testing + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeVDVXUHlZYzluTWc) +- Last Modified: 2016-04-12 + +### Module Loading — Past, Present, Future + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeem9ZOEF3YWR5d3c) +- Last Modified: 2016-04-12 + +### Server-Side Rendering Isn’t Enough + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeY0pFWGJjQ2s4MHM) +- Last Modified: 2016-01-25 + +### DoneJS Overview + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeak9BMWVOelIzR0E) +- Last Modified: 2016-01-25 + +### Building SPAs the “right” way + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeQmhxWUprOUdZQ1E) +- Last Modified: 2016-01-15 + +### can-set + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeVEtLOTd6RGVlbEE) +- Last Modified: 2015-08-21 + +### can-connect + +- [Download](https://drive.google.com/open?id=0Bx-kNqf-wxZeb0FuUUJJX2t3Nms) +- Last Modified: 2015-08-21 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