From 16bd8c02dcd18ab8c6c926da966a23cd55dffd08 Mon Sep 17 00:00:00 2001 From: Tom Page Date: Tue, 9 Apr 2019 11:59:01 +0100 Subject: [PATCH] SEARCH-1513 ADRs for combining the search codebases. --- .../decisions/0003-combined-codebase.md | 46 +++++++++++++++++++ .../decisions/0004-community-mirror.md | 36 +++++++++++++++ .../0005-merge-tests-and-production-code.md | 25 ++++++++++ 3 files changed, 107 insertions(+) create mode 100644 search-services/alfresco-search/doc/architecture/decisions/0003-combined-codebase.md create mode 100644 search-services/alfresco-search/doc/architecture/decisions/0004-community-mirror.md create mode 100644 search-services/alfresco-search/doc/architecture/decisions/0005-merge-tests-and-production-code.md diff --git a/search-services/alfresco-search/doc/architecture/decisions/0003-combined-codebase.md b/search-services/alfresco-search/doc/architecture/decisions/0003-combined-codebase.md new file mode 100644 index 000000000..6f7bc45be --- /dev/null +++ b/search-services/alfresco-search/doc/architecture/decisions/0003-combined-codebase.md @@ -0,0 +1,46 @@ +# 3. Combined Codebase + +Date: 09/04/2019 + +## Status + +Approved + +## Context + +Historically Alfresco has had a bad experience of having a monolithic codebase in SVN. The main issue with this was the +inability to easily work on feature branches, resulting in frequent conflicting changes. To make matters worse this was +seen as hard to move to git, since GitHub has/had a maximum limit on repository size and there were several large +binary artifacts stored in the Alfresco history [[1]]. + +More recently the Alfresco codebase has been split into a large number of small git repositories [[2]]. + +This proposal is to merge the various git repositories together. By doing this we aim to: + +1. Remove the effort of creating releases of library projects. +1. Allow tests to be written on the same branch (in the same repository) as the production code (i.e. facilitate TDD). +1. Make it easier for everyone (especially people outside the team and new starters) to find the 'right bit' of code. + +[1]: https://community.alfresco.com/community/ecm/blog/2015/04/01/so-when-is-alfresco-moving-to-github + +[2]: https://ts.alfresco.com/share/proxy/alfresco/api/node/content/versionStore/version2Store/a0c2492f-6354-4b98-adfc-e63d5c2209f5/SearchCodeBase.png + +## Decision + +We will merge the search-related repositories together and preserve their history. We will not attempt to merge code +that other teams also need (for example the TAS test utilities or the alfresco-data-model projects). + +## Consequences + +An epic has been raised containing the next steps [[3]]. Broadly speaking these are: + +1. Merge the alfresco-solr-client library with the SearchServices repository. +1. Merge the insight-engine, insight-jdbc and insight-zeppelin repositories. + 1. A consequence of this is that future releases of these artifacts will share version numbers. +1. Put all the end-to-end tests in a single testing project. +1. Merge the (public) SearchServices code into the (private) InsightEngine repository and set up a mirror so the +community code is still publicly editable. +1. Merge the tests with the production code. +1. Merge the build scripts with the production code. + +[3]: https://issues.alfresco.com/jira/browse/SEARCH-1393 diff --git a/search-services/alfresco-search/doc/architecture/decisions/0004-community-mirror.md b/search-services/alfresco-search/doc/architecture/decisions/0004-community-mirror.md new file mode 100644 index 000000000..c709c72e1 --- /dev/null +++ b/search-services/alfresco-search/doc/architecture/decisions/0004-community-mirror.md @@ -0,0 +1,36 @@ +# 4. Community Mirror + +Date: 09/04/2019 + +## Status + +Proposed + +## Context + +In [ADR 3: "Combined Codebase"](0003-combined-codebase.md) we decided to merge the Search Services and Insight Engine +repositories. Since we want to enable the community to submit pull requests to the Search Services project we need a +way to keep this code up to date on GitHub. + +## Decision + +We will mirror the alfresco-search-parent submodule of `master` along with all branches starting with `release/` to a +branch with the same name on GitHub. We will include this command as part of our build to do this: + +```git subtree push -P alfresco-search-parent out $targetBranch``` + +## Consequences + +A ticket has been raised to track this [[1]]. A script has been written to do the initial codebase merge and +mirroring [[2]]. + +We will rewrite the whole history of the SearchServices repository using the mirroring command (the only change will be +the commit ids). + +Any changes within a module called alfresco-search-parent will be mirrored. Any changes outside this will not be +mirrored. + +!!! TODO: Check if the community can build the submodule without access to the parent pom file !!! + +[1]: https://issues.alfresco.com/jira/browse/SEARCH-1397 +[2]: https://git.alfresco.com/search_discovery/combinerScript/blob/master/combineSearch.sh diff --git a/search-services/alfresco-search/doc/architecture/decisions/0005-merge-tests-and-production-code.md b/search-services/alfresco-search/doc/architecture/decisions/0005-merge-tests-and-production-code.md new file mode 100644 index 000000000..cb4191f10 --- /dev/null +++ b/search-services/alfresco-search/doc/architecture/decisions/0005-merge-tests-and-production-code.md @@ -0,0 +1,25 @@ +# 5. Merge Tests And Production Code + +Date: 09/04/2019 + +## Status + +Proposed + +## Context + +In [ADR 3: "Combined Codebase"](0003-combined-codebase.md) we decided to merge the production and end-to-end test +repositories. In [ADR 4: "Community Mirror"](0004-community-mirror.md) we discuss setting up a mirror for code within a +particular submodule. + +## Decision + +We will separate the end-to-end test code in half so that any code solely related to Insight Engine won't be mirrored. + +We will remove the existing test groups for the different versions of Search Services and Insight Engine, and instead +delete any tests from branches where they should not be run. + +## Consequences + +It will be possible to include production code changes along with all required test changes in the same merge request. +It will be easy to get new tests running before production code is written without causing other branches to fail.