# CodeRefinery definitions

:::danger

These guidelines are work in progress and only a first draft

:::

[TOC]

:::info

> Note: These definition exists to support the decision if a workshop is a CodeRefinery workshop or not, in case someone wants to call it that. The same applies for hosting materials under CodeRefinery. The definitions are not meant as advertizing to host material under CodeRefinery nor make people want to call their workshops CodeRefinery workshops. But in case someone asks, we would have an answer.

:::

## CodeRefinery infrastructure

- CodeRefinery webpage: coderefinery.org
- Registration system: indico.neic.no
- GitHub organization: github.org/coderefinery
- Twitch channel: twitch.tv/coderefinery
- YouTube channel: youtube.com/@coderefinery
- Newsletter: postit.csc.fi/sympa/subscribe/coderefinery
- Collaborative notes: notes.coderefinery.org
- Zenodo community space: zenodo.org/communities/coderefinery/records

## CodeRefinery hosted materials

The CodeRefinery project maintains open lesson materials to promote sustainable, reproducible, and collaborative research software practices. While anyone is welcome to reuse or adapt our materials under a CC-BY license, only certain materials are hosted under the CodeRefinery GitHub organization (github.com/coderefinery). This section defines what qualifies as CodeRefinery-hosted material and the responsibilities that come with it.

Hosting materials under CodeRefinery gives them visibility, infrastructure, and stewardship by the community. To ensure quality and sustainability, this designation should only be used for materials that meet clear criteria.

### Benefits of hosting materials under CodeRefinery

**1. Visibility & community connection**
- Closeness to other related materials -> shared identity, community interest
- Linked from CodeRefinery webpage
- Shows that materials are open for community contributions

**2. Contribution & collaboration infrastructure**
- Hosting infrastructure on GitHub
- Contribution guide (TBD)
- Review and maintenance support

**3. Support from CodeRefinery partners**
- CodeRefinery partners can work on the material on their CodeRefinery designated time

### When can material be hosted under CodeRefinery?

To include lesson materials within the CodeRefinery ecosystem, the material should meet all the following minimum requirements:

**1. Topical relevance**

Materials must fit clearly within CodeRefinery’s mission:
- Research software development skills
- Collaborative workflows, good practices, FAIR and open science
- Tools and methods that support scientific research software sustainability
- Cross disciplinary

Materials outside this scope may still be welcomed if they complement the ecosystem and have a clear use-case.

**2. Open development + an open license**

Materials must:
- Be openly developed
- Use an open license
- Include attribution to other materials where necessary

This supports transparency, reusability, and longevity.

**3. Identifiable maintainers**

Hosted materials must have:
- At least one named maintainer or maintaining team
- A commitment to keeping the material functional
- (A plan for what happens if the maintainer steps back)

We do not require constant maintenance, only that the material is not abandoned without a plan.

**4. Quality and alignment with the CodeRefinery style**

Materials should:
- Follow CodeRefinery’s modular and example-driven structure where possible
- Include learning goals, prerequisites, exercises/discussions, and instructor guidance
- Use accessible, inclusive language
- Be structured to support live coding or hands-on practice
- Include a clear version history and changelog (Git history is sufficient)

Not all materials need to be polished (work in progress is welcome) but they must meet a basic standard of clarity and usability.

It is recommended, though not necessary, that materials hosted under CodeRefinery are built using the CodeRefinery lesson template. A similar look and feel is wished, but can be discussed. We are also happy to support porting materials from any format to the CodeRefinery template.

### When should material NOT be hosted under CodeRefinery?

- **Highly domain or infrastructure-specific** content that is not broadly relevant across scientific fields / different infrastructures
- **Topics outside scientific computing**, software development for research, or adjacent skills
- **Single-author materials** with no intention or realistic path towards collaboration
- **Materials lacking transparency** about sources, provenance, or external dependencies
- **Materials with restrictive licenses** that limit reuse, modification, or redistribution
- (One-off or short-lived materials with no plan for continued use or development)
- (Unmaintained or abandoned materials)

---

## CodeRefinery workshop

The CodeRefinery project provides open lesson materials that can be reused freely under a CC-BY license. We also organize and support workshops based on these materials.

This section defines what qualifies as a **CodeRefinery workshop** and sets out the criteria for using this label. While we strongly encourage reuse and adaptation of our materials, the term "CodeRefinery workshop" should be used only when specific conditions are met. This ensures consistency, maintains quality, and protects the reputation of the project.

### What is a CodeRefinery Workshop?

A **CodeRefinery workshop** is an educational event that teaches tools and techniques around programming for research, using the CodeRefinery teaching approach and materials. These workshops are grounded in open science principles and designed to be inclusive, collaborative, and practically focused for learners across scientific domains.

There are two main categories:

**1. _The_ CodeRefinery workshop**

This refers to the core, multi-day "tools" workshop that covers key topics such as version control, reproducibility, modular code, and documentation. It is typically taught online by a team of instructors, using live coding and a collaborative document.

**2. Other CodeRefinery workshops**

These include additional workshops developed or endorsed by CodeRefinery which also follow the CodeRefinery teaching philosophy and use its infrastructure.

### Benefits of being a "CodeRefinery workshop"

**1. Visibility and reach**
- Listing on CodeRefinery website
- Mention on CodeRefinery outreach channels
- Trust and recognition
- Certificate from CodeRefinery
- Advertisement via CodeRefinery partners
- Time-zone-aware scheduling, ensuring all CodeRefinery partners can participate

**2. Support and infrastructure**
- Use of CodeRefinery infrastructure
- Support from experienced instructors, onboarding
- Instructor coordination and organization support
- CodeRefinery partners can support the workshop on their CodeRefinery designated time

**3. Quality assurance and pedagogical benefits**
- Co-teaching model
- Peer review and guidance
- Feedback, debrief and improvement

### When can you call it a "CodeRefinery workshop"?

To refer to your event as a CodeRefinery workshop, you **must meet all of the following minimum requirements**:

1. **Use of CodeRefinery materials**
- At least two-thirds of the content must be based on official CodeRefinery lessons.
- Adaptations or forks must link clearly back to the original materials.

2. **Affiliation**
At least one organizer or instructor must:
- Be a CodeRefinery project member, OR
- Have completed CodeRefinery instructor training, taught in a previous CodeRefinery workshop, and maintain some level of contact with the project.

3. **Connection and communication with the project**

- Inform the CodeRefinery team about the workshop ahead of time
- Share participant numbers, feedback, and key takeaways afterwards (via blog post, debrief, or informal message)

This helps us track impact and include your event in our reporting and community updates.

3. **Adherence to CodeRefinery’s Code of Conduct**
- The workshop must follow the [CodeRefinery Code of Conduct](https://coderefinery.org/code-of-conduct/) or similar, and this should be clearly communicated to participants.
- Organizers are responsible for handling any CoC violations appropriately.

> Note: If the workshop is open to external participants, the CodeRefinery team can help advertise it.

#### Recommended best practices (strongly encouraged)

These aren’t mandatory, but they are strongly encouraged to preserve the CodeRefinery spirit:

- The workshop should be free of charge and openly accessible.
- Use co-teaching: no one should teach a lesson alone.
- A collaborative document should be available for Q&A and participant interaction.
- Use live coding with learner-paced instruction.
- Keep all materials under an open license and share any adaptations publicly.
- Adaptations for specific domains are welcome.
- Use CodeRefinery infrastructure where reasonable and possible (we can help with that, e.g., GitHub org, streaming, registration tools).

## Workshops that use CodeRefinery materials but aren’t “CodeRefinery Workshops”

You’re welcome and encouraged to use CodeRefinery materials in your teaching!
However, if your event doesn’t meet the criteria above, please don’t call it a “CodeRefinery workshop.”

Instead, feel free to say that your event:
- Uses CodeRefinery materials, or
- Is inspired by CodeRefinery

**Please avoid suggesting an official affiliation if one doesn’t exist.**

## Why These Guidelines?

These criteria help us:
- Ensure high-quality, consistent learning experiences
- Maintain trust in the CodeRefinery name
- Enable sustainable collaboration and improvement
- Encourage reuse of our open materials in a responsible way

**When in doubt, please contact** [e-mail].

END of draft

---

Examples of current CodeRefinery materials:

- All repositories related to CodeRefinery main workshop, except that they do not have clear maintainers :white_check_mark:
- Python for scicomp -> Could be moved to CR
- TTT4HPC -> Could be moved to CR
- Reproducibility in machine learning workshop - Could be moved to CR
- CodeRefinery and related topics for data stewards (https://github.com/coderefinery/programming4ds etc.) -> Can stay?
- HPC python -> Could be moved to CR, generalized
- HPC kickstart -> Maybe not (applies to only some clusters?)
- https://github.com/coderefinery/BioNT_Lesson_Accelerated_Genomics -> no?
- https://github.com/coderefinery/NumPy-and-Pandas-fundamentals-for-handling-biological-datasets -> no?
- https://github.com/coderefinery/intermediate-python-ml -> ?
- https://github.com/coderefinery/data-visualization-python -> yes?
- https://github.com/coderefinery/python-progression -> yes?
- https://github.com/coderefinery/qaibootcamp ?
- https://github.com/coderefinery/snakemake_hackathon -> yes?
- https://github.com/coderefinery/github-without-command-line -> yes?
- https://github.com/PDC-support/build-systems-course -> if wished
...

---

Additional thoughts from Enrico: https://hackmd.io/@coderefinery/HyTez6-xbe

Answers from team (during kick-off)

## If you would need to define what is a CodeRefinery workshop: what are the requirements to use the name?

- Use the materials
- Follow the code of conduct
- Maybe at least one with instructor training

I think that anything being taught can be linked to CodeRefinery as long as the person teaching has gotten approval from a CodeRefinery team member and the teaching follows the principles that CodeRefinery embodies.

There is THE CodeRefinery workshop (the "tool" workshop) and then there are other CodeRefinery workshops (TTT4HPC, python for sci comp)... Maybe if materials are hosted under coderefinery organisation and/or if streaming or youtube is under coderefinery, then it is a coderefinery workshop...?

The workshop need to use 2/3 to 3/4 of the CodeRefinery Material.

Open material distribution, Open access to the course, online distribution and inclusion, questions presented and answered in some form of collaborative document (were participants can edit)

Live coding content paced in a way that students can follow along.

Having never attended or taught a CodeRefinery training yet, I do not have an intuition for this.
I guess if both the organizers of the workshop and some fraction of the CR instructors agree, it could be branded as such.

Can we go through and identify what should and shouldn't be, from our examples (main lessons at our partners).

I'd like to hear what others think, because I'm not sure. First thoughts to me:

- The core selected lesson materials of the main workshop
- The core workshops we recommend everyone to take.
- Everything in the CR teaching style (perhaps with proportional attendance of instructor/lesson designer training?)
- It could be only we give "coderefinery workshops" but others give "workshops with coderefinery materials" (I'm not sure we have time to manage a whole ecosystem, or if we need to)

To me it's almost synonomous with a workshop which is: user-centric (for diverse new learners, not highly specalized), online, livestream, with good exercises and open materials

- the workshop needs to use our materials or a fork of our materials
- allow for some flexibility to tailor the content to match a certain group
- team instructor optional
- I think we'd get more CR-branded workshops if the requirements are low
- one requirement should nevertheless be: specify how instructor is connect to the CR project, if so, and report back to CR about the workshop

I think we should be fairly strict with letting activities and event be held and announced with referral to the CodeRefinery name. To my knowledge use of our material and referral to the CodeRefinery have commonly been in done in a context where our materials have been used, people on the team have been involved