The maturity of Alfresco products comes from the contributions of the open source community. Contributing back to Alfresco can be a bit confusing as Alfresco products are a collection of separate open source projects. Each open source project officially sponsored by Alfresco has a page in this space detailing its governance policy and the method for reporting issues and submitting contributions. See the tag for "project overview".
This page explains the process for the ECM Repository that makes up Alfresco Community Edition. This process works well for bug fixes and smaller contributions, but doesn't work as well for significant new functionality. If you are planning to contribute a large chunk of work, please see the note at the end.
Do not reformat code as it hides useful changes; add a comment indicating that a separate reformat may be required, if necessary
If your change impacts more than one repository, the pull requests should cross-reference each other and reference the same ALF issue. Make sure to clarify the dependency order (ie. order of merging). Also, please make sure the pull requests / merge requests follow the contribution guidelines such as including proper tests, documentation, localization, etc.
Add or change the tests to check the code. The test coverage should be enough to prove the change worked and to prevent regressions in future.
Please, pay attention to the level of test being done. It is preferred to create unit tests as opposing to system/integration tests. Unit tests are simpler, easier to maintain and take less time to run.
Keep the test short - it should finish under ~2 seconds
Use mocks to ensure good performance
In the tests that do require an application context, do not use static references to the application context. Use instance variables for the application context, and then:
Reference your pull request (preferred) or attach the patch.
Add the 'PatchAttached' label to your issue.
Keep track of your JIRA issue number in case discussion is required before the contribution is accepted.
Finally, let everyone know you're an Alfresco Contributor!
Pull Request Commit Messages
A clear commit message on your pull request will make it easy to understand the goal of your change at the time we review your pull request and throughout the life of the code base. The following guidelines will help you to provide a commit message that is useful, and that works well with various development tools.
Separate the subject from the body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Include JIRA numbers in the subject line
Wrap the body at 72 characters
Use the body to explain the what and why vs. the how
Use a hyphen as a bullet point in the lists
Example: ~~~ ALF-12345 Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of the commit and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); various tools like `log`, `shortlog` and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you are making this change as opposed to how (the code explains that). Are there side effects or other unintuitive consequences of this change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too - Use a hyphen for the bullet, preceded by a single space ~~~
Contributing Significant New Functionality
We appreciate the interest people have in making significant contributions to Alfresco Products. Because Alfresco will be owning the long term maintenance of the contribution, we need to ensure it fits into our vision for the product and its architecture. Because of the effort necessary to evaluate a major contribution (including architecture and UX) and accept it (including documentation, localization, and support training), we also need to verify that the proposed contribution is more important than the other work currently on our roadmap.
If you would like to contribute a significant enhancement to an Alfresco product, we encourage you to discuss it with us as early as possible. This will allow us to collaborate on the requirements for the contribution so that it fits into our broader architecture and minimizes the effort required to accept the work. It will also allow us to have a conversation about relative prioritization so that we can understand if there is alignment in our schedules.
The most common motivation for making a significant contribution is to reduce the effort in maintaining the functionality as customizations. Following modern best practices for Alfresco module development will reduced the cost of building and maintaining even substantial customizations. In addition, sharing those modules with the open source community on GitHub or on Alfresco Addons can allow you to benefit from collaboration with other developers. In our experience, most large contributions to the ECM Repository are better implemented as community modules. We regularly review the most popular modules in the Alfresco ecosystem and have previously brought many of them into the product.