Submitting Contributions

[resplin]

• Contributing a fix or small enhancement
• 1. Get Alfresco ready for patching
• 2. Make your change
• 3. Share your contribution
• Pull Request Commit Messages
• Contributing Significant New Functionality

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.

Contributing a fix or small enhancement

1. Get Alfresco ready for patching

1. Find the appropriate project in the Alfresco organization on GitHub. The Project Overview: Content Services‌ section of this community can help you identify the correct code repository.
2. Clone the project with: git clone {project-url}.
3. Setup your development environment to enable the execution of unit tests.

2. Make your change

1. Update the source code to implement the fix or enhancement.
   1. Follow the Coding Standards for Alfresco Content Services 
   2. Do not reformat code as it hides useful changes; add a comment indicating that a separate reformat may be required, if necessary

   3. 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.

2. 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:

     applicationContext = ApplicationContextHelper.getApplicationContext();

     in the setup method of the tests, to get the desired context reference.
   • Use all the other common sense practices for writing good unit tests:
     • clean up after the tests - ensure that the cleanup happens even if the test fails
     • don't use the "sleep()" method
     • consider side effects on other tests/test classes (unregister listeners, restore authentication methods/authenticated users, reset internationalization settings if changed...)
     • if test data needs to be created and persisted, it should have random ( GUID.generate(), System.currentTimeMillis() ) names to avoid clashes. etc.
   • Keep the tests classes and test methods focused on testing a certain functionality in a similar manner.
   • Avoid (costly) application context loads, refreshes, reloads or switches.
   • Keep/add proper tests in the correct project, so that there would not be a need to run other project's tests to validate the code/functionality from another project.
3. Verify that all (existing and new) tests pass successfully.
4. Ensure that strings are available for localization, but you do not need to provide localization as our team will do that.
5. Consider including basic documentation with your contribution.

3. Share your contribution

Our team checks our GitHub and JIRA issue tracking system for submitted patches, and merges them into the code base. More information is on the page Reporting an Issue‌. Please read the recent changes to how to contribute to Alfresco.

1. Create a patch of your changes.
   • Create a pull request against the public project on GitHub.
     • Describe what is in the code and include the JIRA number of the reported bug if applicable.
     • The pull request format should follow the Pull Request Commit Message format (see below).
   • OR (not preferred) generate a patch diff file: git format-patch -1 {commit-id} --stdout > {appropriate_name}.patch
2. Create a new GitHub issue in the ALF project.
   • We require an ALF issue because:
     • we work on multiple GitHub repositories and accept contributions of a variety of types.
     • issues can be linked to or moved into other workflows
     • a fix or contribution may span multiple libraries
     • additional work resulting from a change can be high lighted and tracked through new JIRA tickets.  For example:
       • New or altered end-user text
       • Changes to documentation
   • When you submit the issue, you will be asked to accept the Alfresco Contribution Agreement‌.
   • Reference your pull request (preferred) or attach the patch.
   • Add the 'PatchAttached' label to your issue.
3. Keep track of your JIRA issue number in case discussion is required before the contribution is accepted.
4. 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.

Please:

• 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.

[sorin_postelnic]

Could you please clarify how to proceed in this case:

If I want to submit a bugfix for an ALF ticket that has already been created by someone else, how can I "sign" the Contributors Agreement?

[derek]

Create a new issue and link it to the original you are fixing.  It's better as it gives you a bit more room to describe your fix and the conditions around it.
Thank you and we look forward to reviewing the change.