diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..0bb60164b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,147 @@ +# Contributing to Alfresco Content Application (ACA) + +We would love for you to contribute to Alfresco Content Application and help make it ever better! +As a contributor, here are the guidelines we would like you to follow: + +* [Code of Conduct](#coc) +* [Question or Problem?](#question) +* [Issues and Bugs](#issue) +* [Feature Requests](#feature) +* [Submission Guidelines](#submit) +* [Coding Rules](#rules) +* [Signing the CLA](#cla) + +## Code of Conduct + +Help us keep Alfresco Content Application open and inclusive. +Please read and follow our [Code of Conduct][coc]. + +## Got a Question or Problem? + +Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. +You've got much better chances of getting your question answered on [Gitter][gitter]. + +The ADF [Gitter][gitter] channel is a much better place to ask questions since: + +* many people that can help +* questions and answers stay available for public viewing so your question / answer might help someone else +* all discussions are saved and indexed, you can search for previous answers + +## Found a Bug? + +If you find a bug in the source code, you can help us by: + +* [submitting an issue](#submit-issue) to our [ACA JIRA project][jira] +* [submitting an issue](#submit-issue) to our [GitHub Repository][github]. + +Even better, you can [submit a Pull Request](#submit-pr) with a fix. + +## Missing a Feature? + +You can *request* a new feature by [submitting an issue](#submit-issue) +to our [JIRA project][jira] or GitHub Repository. +If you would like to *implement* a new feature, please submit an issue with a proposal for your work first, +to be sure that we can use it. + +Please consider what kind of change it is: + +* For a **Major Feature**, first open an issue and outline your proposal so that it can be +discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, +and help you to craft the change so that it is successfully accepted into the project. +* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). + +## Submission Guidelines + +Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists +and the discussion might inform you of workarounds readily available. + +We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. +In order to reproduce bugs, we will systematically ask you to provide a minimal reproduction scenario. +Having a reproducible scenario gives us a wealth of important information without going back & forth to you with additional questions like: + +* version of node.js used +* version of NPM used +* version of Angular used +* versions of ADF libraries used +* 3rd-party libraries and their versions +* and most importantly - a use-case that fails + +You can file new issues by filling out our [new issue form](https://github.com/Alfresco/alfresco-content-app/issues/new). + +### Submitting a Pull Request (PR) + +Before you submit your Pull Request (PR) consider the following guidelines: + +1. Search [GitHub](https://github.com/Alfresco/alfresco-content-app/pulls) for an open or closed PR + that relates to your submission. You don't want to duplicate effort. +1. Please sign our [Contributor License Agreement (CLA)](#cla) before sending PRs. + We cannot accept code without this. + Make sure you sign with the primary email address of the Git identity that has been granted access to the Angular repository. +1. Fork the ACA repository. +1. Make your changes in a new git branch based on **development**: + + ```shell + git checkout -b my-fix-branch development + ``` + +1. Create your patch, **including appropriate test cases**. +1. Follow our [Coding Rules](#rules). +1. Run the full ACA test suite and ensure that all tests pass. +1. Commit your changes using a descriptive commit message. +1. Push your branch to GitHub: + + ```shell + git push origin my-fix-branch + ``` + +1. In GitHub, send a pull request to `alfresco-content-app:development`. +* If we suggest changes then: + * Make the required updates. + * Re-run the ACA test suites to ensure tests are still passing. + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): + + ```shell + git rebase development -i + git push -f + ``` + +That's it! Thank you for your contribution! + +## Coding Rules + +To ensure consistency throughout the source code, keep these rules in mind as you are working: + +* All features or bug fixes **must be tested** by one or more specs (unit-tests). +* All public API methods **must be documented**. + +## Signing the CLA + +Please sign our [Contributor License Agreement (CLA)][cla] before sending pull requests. +In addition, you will get the CLA link automatically generated for your first pull request. + +For any code changes to be accepted, the CLA must be signed. +It's a quick process, we promise! + +
+ +If you have more than one Git identity, you must make sure that you sign the CLA using the primary +email address associated with the ID that has been granted access to the Angular repository. +Git identities can be associated with more than one email address, and only one is primary. + +Here are some links to help you sort out multiple Git identities and email addresses: + + * https://help.github.com/articles/setting-your-commit-email-address-in-git/ + * https://stackoverflow.com/questions/37245303/what-does-usera-committed-with-userb-13-days-ago-on-github-mean + * https://help.github.com/articles/about-commit-email-addresses/ + * https://help.github.com/articles/blocking-command-line-pushes-that-expose-your-personal-email-address/ + + Note that if you have more than one Git identity, it is important to verify that you are logged in + with the same ID with which you signed the CLA, before you commit changes. If not, your PR will fail the CLA check. + +
+ +[coc]: https://github.com/Alfresco/alfresco-content-app/blob/master/CODE_OF_CONDUCT.md +[github]: https://github.com/Alfresco/alfresco-content-app +[gitter]: https://gitter.im/Alfresco/alfresco-ng2-components +[jira]: https://issues.alfresco.com/jira/projects/ACA +[cla]: https://cla-assistant.io/Alfresco/alfresco-content-app