ADR Suggestion, EasyScience Organization Repositories

[AndrewSazonov]

Proposal to Rename EasyScience Organization Repositories

The EasyScience organization currently includes 50 repositories. It has become challenging to navigate and track them efficiently.

To address this, I propose a systematic renaming repositories to improve clarity and usability. The key changes include:

1. Removing the "Easy" Prefix:

   • Repository names like "EasyDiffractionLib" will be shortened to "diffraction-lib" to reduce redundancy and improve readability.
   • The "Easy" prefix is unnecessary as all repositories are under the EasyScience organization, which already establishes their association.
   • Note: This suggestion applies only to repository names, not project names. For instance, the project will still be called "EasyDiffraction," and Python packages will retain their names, such as easydiffraction, easyreflectometry, easyscience, etc.

2. Grouping Repositories by Categories:

   • Repositories are organized into logical groups (e.g., specific projects, generic projects, common resources, third-party dependencies) to make navigation easier.

Below are the proposed changes for repository names, categorized for clarity. The first column lists the new repository name, and the second column provides a description to be aligned with the "About" section of the repository.

Note: QENS is not mentioned yet because the final decision on the name of the project has not yet been made.

---

Technique-specific Projects

EasyDiffraction

Repository	Description
diffraction	Launching point for the EasyDiffraction family of repositories
diffraction-lib	Python library for diffraction data analysis
diffraction-app	Desktop application for diffraction data analysis
diffraction-page	Main web page for EasyDiffraction
diffraction-lib-docs	User documentation for the diffraction library
diffraction-app-docs	User documentation for the diffraction application

EasyReflectometry

Repository	Description
reflectometry	Launching point for the EasyReflectometry family of repositories
reflectometry-lib	Python library for reflectometry data analysis
reflectometry-app	Desktop application for reflectometry data analysis
reflectometry-page	Main web page for EasyReflectometry

EasyImaging

Repository	Description
imaging	Launching point for the EasyImaging family of repositories
imaging-lib	Python library for Bragg-edge imaging data analysis
imaging-app	Desktop application for Bragg-edge imaging data analysis

EasyTexture

Repository	Description
texture-app	Desktop application for texture data reduction

---

Generic Projects

Repository	Description
.github	EasyScience organization profile
easyscience-core	Core building blocks for Python libraries in the EasyScience framework
easyscience-app	Graphical components for desktop applications in the EasyScience framework
easyscience-crystal	Backend crystallographic tools in the EasyScience framework
easyscience-page	Main web page for the EasyScience organization

---

Common Resources

Repository	Description
assets-branding	Logos, icons, and branding assets for the entire organization
assets-page	Shared assets for project web pages
assets-docs	Shared assets for project documentation
templates-project	Copier template for technique-specific EasyScience projects

---

Other EasyScience Repositories

Repository	Description
pypi	Custom Python package index for EasyScience-based libraries

---

Third-Party Projects

Repository	Description
dependencies-cryspy	Custom version of the CrysPy library
dependencies-pdffit2	Custom version of the diffpy.pdffit2 library
dependencies-pycrysfml	Python bindings for the CrysFML2008 library

[rozyczko]

This looks very good. I wonder if it weren't even more structured if we had a directory structure in our repo, like

 ├───EasyScience
 |   └───Diffraction
 |          └───Lib
 |          └───App
 |          └───Docs
 |          └───Www
 |   └───Reflectometry
 |          └───Lib
 |          └───App
 |          └───Docs
 |          └───Www
 |   └───Common
 ...

This can be achieved with either submodules or a monorepo.

[AndrewSazonov]

Monorepo and submodules seem like interesting alternatives to the current approach. However, while both approaches offer advantages, they also introduce complexities that may outweigh their benefits in our specific case.

Monorepo challenges:

• Increased Build Complexity:
  • Our existing build scripts, which already include conditional logic, would require even more granular checks. For instance:
    • Modifications to the main web page should not trigger builds for the library, app, or their respective documentation.
    • Changes to the app would often not require building the library or its documentation.
  • Managing these distinctions in a monorepo would demand more complex CI/CD workflows.
• Workflow Management:
  • Currently, each repository has its own workflows visible on the GitHub Actions page. Combining multiple repositories into one would significantly increase the number of workflows in a single list.
  • Naming workflows to indicate their corresponding sub-project (e.g., “diffraction-app-build”) would add complexity and reduce readability.
  • Filtering workflows by branch or sub-project would also become more challenging.
• Release Management:
  • The library and application have separate release cycles. A monorepo would make tagging releases problematic, as it would be unclear whether a tag corresponds to a library release, an app release, or both.
  • Maintaining independent versioning for different components in a monorepo can be cumbersome.
• Merge Conflicts:
  • The likelihood of conflicts would increase, especially when multiple contributors work on different parts of the repository simultaneously. This could slow down development.
• Repository Size:
  • Over time, a monorepo could become very large, making operations like cloning or searching slower.

Submodules challenges:

• Complex Development Workflow:
  • Developers must initialize and update submodules explicitly when cloning or pulling changes. This adds friction, especially for new contributors.
  • Submodules track specific commits, not branches, requiring extra effort to keep them in sync with the latest changes.
• CI/CD Pipeline Complexity:
  • Integrating submodules into CI/CD pipelines requires additional configuration to ensure the correct versions of submodules are checked out and built together.
• No Reduction in Repositories:
  • Unlike a monorepo, submodules do not consolidate repositories. While they improve organization, they do not simplify repository management.

While both the monorepo and submodules approaches have potential advantages, they introduce significant complexities in terms of workflow, build pipelines, and release management. Given these considerations, I suggest adopting the simpler solution of renaming and reorganizing the existing repositories as proposed in the original comment.

By starting with a simpler renaming strategy, we can achieve immediate improvements in organization and usability while avoiding the challenges and overhead of more complex solutions. Over time, if we find additional structure beneficial, we can reconsider options like a monorepo or submodules.

[rozyczko]

Some comments on the common modules names

EasyCrystallography -> easyscience-crystal: crystal sounds more like a library for single crystal to me, maybe the full name easyscience-crystallography or easyscience-symmetry?

EasyApp -> easyscience-app: -app does not immediately convey that this is a GUI-related library. Maybe easyscience-gui or easyscience-guilib (this is a library, not a standalone app).

EasyScience -> easyscience-core: -core - maybe we should, again, add -lib to signify this is a component easyscience-corelib or easyscience-core-lib

[AndrewSazonov]

Okay, let’s apply these changes for better clarity and consistency:

• EasyCrystallography → easyscience-crystallography
• EasyApp → easyscience-gui-lib
• EasyScience → easyscience-core-lib

[damskii9992]

Writing the comment from our daily discussion here:
Renaming the repositories might interfere with users finding our github repositories when googling for them as they won't be listed with their project names.

[AndrewSazonov]

While renaming repositories might initially affect search visibility, the impact can be minimized by optimizing the README files, as their content is indexed by Google and contributes significantly to search rankings. Therefore, including the project’s full name (e.g., “EasyDiffraction”) in the README file will help maintain visibility even after a repository is renamed. Additionally, descriptions, tags, topics, and other metadata associated with the repository are indexed and also contribute to search rankings.