README.md

EasyScience is a versatile data analysis framework designed to streamline the journey from data collection to publication. It provides:

• Powerful back-end tools: Core functionality through Python libraries.
• Efficient front-end modules: QML components for developing desktop applications with ease.

📖 Table of Contents

1. 🔑 Set Up GitHub Access
2. 📌 Define the Project in the Organization Profile
3. 📦 Create Repositories Using Templates
4. 🚀 Push Changes to GitHub
5. ⚙️ Repository Configuration
6. 🔄 Updating the Repository with Template Changes

1. 🔑 Set Up GitHub Access

GitHub access can be managed via Personal Access Tokens (PATs):

1.1. Generate a Personal Access Token (PAT)

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens.
2. Click "Generate new token".
3. Select:
   • ✅ repo → Full control of repositories.
   • ✅ workflow → Access GitHub Actions (optional).
4. Click "Generate token" and copy it.

1.2. Using PAT

You can now use PAT to interact with GitHub via:

• Terminal (Recommended for advanced users).
• GUI tools (e.g., GitKraken for an intuitive interface).

2. 📌 Define the Project in the Organization Profile

Each project should first be registered under the EasyScience organization profile.

2.1. Add project definition

Edit README.yaml under domain-specific-projects.

2.2. Include the following details:

• name → The project name, prefixed with Easy (e.g., EasyDiffraction).
• shortcut → A short, two-letter abbreviation (e.g., ED).
• description:
  • main → A brief project description (e.g. Diffraction).
  • type → Type of project (e.g., data analysis, data reduction).
• repos:
  • home → Home repository name (e.g., diffraction).
  • lib → Library repository name (if applicable).
  • app → Application repository name (if applicable).

Example (EasyDiffraction)

  - name: EasyDiffraction
    shortcut: ED
    description:
      main: Diffraction
      type: data analysis
    repos:
      home: diffraction
      lib: diffraction-lib
      app: diffraction-app

3. 📦 Create Repositories Using Templates

EasyScience provides predefined Copier templates for new repositories:

To create new repositories within the EasyScience framework, utilize the predefined Copier templates to ensure consistency and streamline the setup process.

Base Template:

The following base template is essential for all projects, regardless of type:

Template	Purpose	Repository
project-base	Foundational project setup	templates-project-base

Project-Specific Templates:

In addition to the base template, select one of the following templates based on your project type:

Template	Purpose	Repository
project-home	Home project repository	templates-project-home
project-lib	Python package repository	templates-project-lib
project-app	Qt QML desktop application repository	templates-project-app

By combining the base template with the appropriate project-specific template, you can efficiently set up a new repository tailored to your project’s requirements.

3.1. Create a repository on GitHub

Here is an example for creating a new repository diffraction-lib which will be a Python library for the project EasyDiffraction. Creating a new repository diffraction-home (project home) or diffraction-app (desktop app) could be done in a similar way.

Create a new repository:

1. Navigate to GitHub → Create New Repository.
2. Repository template: No template (we will use Copier instead).
3. Enter the repository name, e.g., diffraction-lib.
4. Description: Add a description based on the README.yaml definition from above, e.g., Diffraction data analysis.
5. Set repository visibility to Public.
6. DO NOT initialize with a README, .gitignore, or license (Copier handles these).
7. Click "Create repository".

3.2. Clone the repository

git clone https://github.com/easyscience/diffraction-lib.git

3.3. Navigate to the project directory

cd diffraction-lib

3.4. Set up a virtual environment (optional)

python3 -m venv .venv

. .venv/bin/activate      # macOS/Linux
. .venv/Scripts/activate  # Windows with Unix like shells
.\.venv\Scripts\activate.bat   # Windows with CMD
.\.venv\Scripts\activate.ps1   # Windows with Power shell

3.5. Install Copier (if not already installed)

pip install copier

3.6. Generate the project structure with base template

copier copy gh:easyscience/templates-project-base ./

(Follow interactive prompts to configure the project.)

3.7. Extend with additional templates

copier copy gh:easyscience/templates-project-lib ./ --data-file .copier-answers.project-base.yml

(Follow interactive prompts to configure the project.)

(Note: To ensure the base project definition generated by Copier in the previous step is included, we use the --data-file option followed by the path to the answers file)

4. 🚀 Push changes to GitHub

cd diffraction-lib
git add -A
git commit -m "Initial project setup using Copier templates"
git push origin master

(Alternatively, use a GUI client like GitKraken.)

5. ⚙️ Repository Configuration

• Add repository secrets (e.g., API keys, deployment keys).
• Configure branch protection & access control.

6. 🔄 Updating the Repository with Template Changes

6.1. Navigate to the project directory (if not there yet)

cd diffraction-lib

6.2. Update Base Project Definition Templates

copier update --answers-file=.copier-answers.project-base.yml
git add -A
git commit -m "Updated project structure with latest template"
git push origin master

(Alternatively, use a GUI client like GitKraken.)

(If conflicts arise, Copier will prompt you to review them.)

6.3. Update Library-Specific Files

copier update --answers-file=.copier-answers.project-lib.yml --data-file .copier-answers.project-base.yml
git add -A
git commit -m "Updated Python library structure with latest template"
git push origin master

(Note: To ensure the base project definition generated by Copier in the previous step is included, we use the --data-file option followed by the path to the answers file)

(Alternatively, use a GUI client like GitKraken.)

(If conflicts arise, Copier will prompt you to review them.)