From fc0a180b0f4a8ac1076256ff61b07ab397fd3525 Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Fri, 27 Sep 2024 17:54:20 +0200 Subject: [PATCH 01/14] First but not-yet-ready-version of the document --- projects/affiliated.md | 68 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 projects/affiliated.md diff --git a/projects/affiliated.md b/projects/affiliated.md new file mode 100644 index 000000000..6f3f64c8e --- /dev/null +++ b/projects/affiliated.md @@ -0,0 +1,68 @@ +--- +title: "HSF Affiliated Projects and Software" +layout: plain +--- + +HSF Affiliated Projects and Software + +## Definitions + +HSF Affiliated Projects and Software are community-driven and community-oriented “endeavours” or “products” of wide and recognised interest and applicability beyond a single collaboration or experiment. + +HSF Affiliated Projects and Software are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its remit](https://hepsoftwarefoundation.org/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no control over the endeavours/products, hence no responsibility for evolution or maintenance. + +Projects are in general not hosted on the HSF GitHub repository since they are externally managed and maintained, though some are on the [HSF GitHub repository](https://github.com/HSF). + +## Engagement and endorsement + +Any member of the community is welcome to engage with the HSF in general and the HSF Steering Group (SG), in particular to discuss the route towards making a software project or package an HSF Affiliated Project or Software. This can be an informal discussion initially. + +Formal endorsement is provided by the HSF SG following a short evaluation period in consultation with the relevant HSF Working Group conveners and community experts. For transparency, these evaluations (start, scope and end) are advertised publicly via the HSF Forum, the HSF’s main means of communication. + +The list of HSF Affiliated Projects and Software is hosted in a dedicated area on the HSF website, curated and maintained by the HSF SG. + +The recognition of bijective engagement with the HSF is displayed via GitHub Badges. Three levels distinguish mainly the level of maturity, community support and +engagement: Bronze, Silver and Gold. In broad terms, the attribution of the endorsement level is based on the following guidelines, which are detailed in the dedicated document on Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Levels. +- Bronze: new or young endeavour, likely evolving from and within a collaboration or experiment, but with the potential for other communities to use. It should be committed to meeting best practices in software engineering, e.g., documentation and a test suite. +- Silver: aiming for gold but in an earlier phase towards strong community support (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. +- Gold: endeavour adopted by several collaborations and/or experiments with a strong and long-term community support model. + +The HSF envisages a scheme for Annual Project Awards. A concrete proposal will be presented to the HSF Advisory Group once the latter is put in place. + +## Best-practice guidelines + +They are detailed in the document Guidelines for HSF (Affiliated) Projects and Software. + +## HSF “Reviews” + +The HSF can organise informal reviews of community projects upon request. Such reviews bring together a group of experts from the community to assess all aspects of a project or software, from requirements to implementation: code, packaging, documentation, etc. + +The reviews are organised by the HSF SG in consultation with relevant Working Group conveners. For transparency, these reviews (start, scope and end) are advertised publicly via the HSF Forum, the HSF’s main means of communication, and the results are made public. + +## HSF Requirements and Reference Implementation + +The HSF encourages finding common solutions to common problems for the benefit of the community. + +An HSF Project or Software can be realised in practice as a Reference Implementation (RI). An HSF RI for a common problem shall be described via a White Paper defining the problem and the general idea of the solution; the implementation itself will be documented via standard documentation means. The White Paper should solicit input from the whole community, via meetings advertised through the HSF, to make sure the definition of the problem is commonly agreed. + +Where there is a problem domain in the field that has not been studied from a general perspective, the HSF can organise a group of experts to formulate the requirements to solve the problem and to later facilitate the development of a reference implementation. +In the first phase, experts from multiple experiments and communities should undertake a process of writing a White Paper, with wide community consultation and endorsement, which describes the problem to be solved in terms of specific and concrete requirements. +The requirements can then be used as the basis for a public API specification, to which specific solutions should adhere to. +The HSF can facilitate the development of solutions, which will become an Affiliated Project or Software irrespective of the concrete circumstances and sources of effort and funding. +The model for this process was the development of the conditions database used by sPHENIX, as developed by the BNL NPPS group, following the problem definition developed in the HSF Conditions Database Working Group [2401.16274]. + +## Letters of Support and Cooperation + +Please refer to the document HSF letters on the website. The HSF continues to provide letters on the same basis. + +## Funding Support + +The HSF is a community organisation with no internal source of funding. It runs as a do-ocracy. In the spirit that the HSF facilitates cooperation and common efforts in HEP software and computing internationally, the HSF envisages facilitating the availability of modest financial support for community colleagues to travel and present at important events. This is inspired, broadly speaking, by the concept of NumFOCUS Affiliated Projects. The HSF will highlight external funding opportunities available for software projects. + +Entities interested in acting as Sponsors make themselves known to the HSF SG stating the level of funding they will make available per annum, and for what type of activity(ies) - e.g., presentation of a software package by an Early Career Scientist at a major conference, travel support for a seminar. The HSF SG curates the list of Sponsors on the website, displaying the requirements to be met by each Sponsor. The HSF will not be in charge of financial transactions, it will merely serve as a mediator. + +Entities can be any moral entity or persons. + +The HSF does not envisage delivering a programme of software development grants or any grants of any kind. It also cannot accept direct donations, which should rather be made available via a sponsor’s funding opportunity. + +The HSF may re-assess its indirect funding scheme at any time and the SG welcomes feedback on this new initiative. From e48e6de17c7b2489a39b7dfe793a3b869c222b50 Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Fri, 27 Sep 2024 18:12:07 +0200 Subject: [PATCH 02/14] Finalised with minor edits and links added --- projects/affiliated.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index 6f3f64c8e..7d155d335 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -7,25 +7,28 @@ HSF Affiliated Projects and Software ## Definitions -HSF Affiliated Projects and Software are community-driven and community-oriented “endeavours” or “products” of wide and recognised interest and applicability beyond a single collaboration or experiment. +*HSF Affiliated Projects and Software* are community-driven and community-oriented "endeavours" or "products" of wide and recognised interest and applicability beyond a single collaboration or experiment. -HSF Affiliated Projects and Software are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its remit](https://hepsoftwarefoundation.org/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no control over the endeavours/products, hence no responsibility for evolution or maintenance. +*HSF Affiliated Projects and Software* are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its remit]({{ site.baseurl }}/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no control over the endeavours/products, hence no responsibility for evolution or maintenance. Projects are in general not hosted on the HSF GitHub repository since they are externally managed and maintained, though some are on the [HSF GitHub repository](https://github.com/HSF). ## Engagement and endorsement -Any member of the community is welcome to engage with the HSF in general and the HSF Steering Group (SG), in particular to discuss the route towards making a software project or package an HSF Affiliated Project or Software. This can be an informal discussion initially. +Any member of the community is welcome to engage with the HSF in general and the +[HSF Steering Group (SG)]({{ site.baseurl }}/organization/team.html), +in particular to discuss the route towards making a software project or package an HSF Affiliated Project or Software. This can be an informal discussion initially. -Formal endorsement is provided by the HSF SG following a short evaluation period in consultation with the relevant HSF Working Group conveners and community experts. For transparency, these evaluations (start, scope and end) are advertised publicly via the HSF Forum, the HSF’s main means of communication. +Formal endorsement is provided by the HSF SG following a short evaluation period in consultation with the relevant HSF Working Group conveners and community experts. For transparency, these evaluations (start, scope and end) are advertised publicly via the HSF Forum, the HSF's main means of communication. The list of HSF Affiliated Projects and Software is hosted in a dedicated area on the HSF website, curated and maintained by the HSF SG. -The recognition of bijective engagement with the HSF is displayed via GitHub Badges. Three levels distinguish mainly the level of maturity, community support and -engagement: Bronze, Silver and Gold. In broad terms, the attribution of the endorsement level is based on the following guidelines, which are detailed in the dedicated document on Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Levels. -- Bronze: new or young endeavour, likely evolving from and within a collaboration or experiment, but with the potential for other communities to use. It should be committed to meeting best practices in software engineering, e.g., documentation and a test suite. -- Silver: aiming for gold but in an earlier phase towards strong community support (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. -- Gold: endeavour adopted by several collaborations and/or experiments with a strong and long-term community support model. +The recognition of bijective engagement with the HSF is displayed via *GitHub Badges*. +Three levels distinguish mainly the level of maturity, community support and engagement: Bronze, Silver and Gold. +In broad terms, the attribution of the endorsement level is based on the following guidelines, which are detailed in the dedicated document on Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Levels. +* Bronze: new or young endeavour, likely evolving from and within a collaboration or experiment, but with the potential for other communities to use. It should be committed to meeting best practices in software engineering, e.g., documentation and a test suite. +* Silver: aiming for gold but in an earlier phase towards strong community support (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. +* Gold: endeavour adopted by several collaborations and/or experiments with a strong and long-term community support model. The HSF envisages a scheme for Annual Project Awards. A concrete proposal will be presented to the HSF Advisory Group once the latter is put in place. @@ -33,11 +36,11 @@ The HSF envisages a scheme for Annual Project Awards. A concrete proposal will b They are detailed in the document Guidelines for HSF (Affiliated) Projects and Software. -## HSF “Reviews” +## HSF "Reviews" The HSF can organise informal reviews of community projects upon request. Such reviews bring together a group of experts from the community to assess all aspects of a project or software, from requirements to implementation: code, packaging, documentation, etc. -The reviews are organised by the HSF SG in consultation with relevant Working Group conveners. For transparency, these reviews (start, scope and end) are advertised publicly via the HSF Forum, the HSF’s main means of communication, and the results are made public. +The reviews are organised by the HSF SG in consultation with relevant Working Group conveners. For transparency, these reviews (start, scope and end) are advertised publicly via the HSF Forum, the HSF's main means of communication, and the results are made public. ## HSF Requirements and Reference Implementation @@ -49,17 +52,25 @@ Where there is a problem domain in the field that has not been studied from a ge In the first phase, experts from multiple experiments and communities should undertake a process of writing a White Paper, with wide community consultation and endorsement, which describes the problem to be solved in terms of specific and concrete requirements. The requirements can then be used as the basis for a public API specification, to which specific solutions should adhere to. The HSF can facilitate the development of solutions, which will become an Affiliated Project or Software irrespective of the concrete circumstances and sources of effort and funding. -The model for this process was the development of the conditions database used by sPHENIX, as developed by the BNL NPPS group, following the problem definition developed in the HSF Conditions Database Working Group [2401.16274]. +The model for this process was the development of the conditions database used by sPHENIX, as developed by the BNL NPPS group, following the problem definition developed in the HSF Conditions Database Working Group [arXiv:2401.16274](https://doi.org/10.48550/arXiv.2401.16274). ## Letters of Support and Cooperation -Please refer to the document HSF letters on the website. The HSF continues to provide letters on the same basis. +Please refer to the document +[HSF letters]({{ site.baseurl }}/organization/hsf-letters.html) +on the website. The HSF continues to provide letters on the same basis. ## Funding Support -The HSF is a community organisation with no internal source of funding. It runs as a do-ocracy. In the spirit that the HSF facilitates cooperation and common efforts in HEP software and computing internationally, the HSF envisages facilitating the availability of modest financial support for community colleagues to travel and present at important events. This is inspired, broadly speaking, by the concept of NumFOCUS Affiliated Projects. The HSF will highlight external funding opportunities available for software projects. +The HSF is a community organisation with no internal source of funding. +It runs as a do-ocracy. In the spirit that the HSF facilitates cooperation and common efforts in HEP software and computing internationally, the HSF envisages facilitating the availability of modest financial support for community colleagues to travel and present at important events. +This is inspired, broadly speaking, by the concept of +[NumFOCUS Affiliated Projects](https://numfocus.org/sponsored-projects/affiliated-projects). +The HSF will highlight external funding opportunities available for software projects. -Entities interested in acting as Sponsors make themselves known to the HSF SG stating the level of funding they will make available per annum, and for what type of activity(ies) - e.g., presentation of a software package by an Early Career Scientist at a major conference, travel support for a seminar. The HSF SG curates the list of Sponsors on the website, displaying the requirements to be met by each Sponsor. The HSF will not be in charge of financial transactions, it will merely serve as a mediator. +Entities interested in acting as Sponsors make themselves known to the HSF SG stating the level of funding they will make available per annum, and for what type of activity(ies) - e.g., presentation of a software package by an Early Career Scientist at a major conference, travel support for a seminar. +The HSF SG curates the list of Sponsors on the website, displaying the requirements to be met by each Sponsor. +The HSF will not be in charge of financial transactions, it will merely serve as a mediator. Entities can be any moral entity or persons. From 4dd75d2fd720a68c55df5ed08b7b0b53a17a1504 Mon Sep 17 00:00:00 2001 From: hegner Date: Thu, 3 Oct 2024 10:59:51 +0200 Subject: [PATCH 03/14] Update projects/affiliated.md Co-authored-by: Eduardo Rodrigues --- projects/affiliated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index 7d155d335..b02e94620 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -34,7 +34,7 @@ The HSF envisages a scheme for Annual Project Awards. A concrete proposal will b ## Best-practice guidelines -They are detailed in the document Guidelines for HSF (Affiliated) Projects and Software. +They are detailed in the document Guidelines for HSF Affiliated Projects and Software. ## HSF "Reviews" From f35c217b0c0e989e5ab2e8ad206259cc3716a2d2 Mon Sep 17 00:00:00 2001 From: hegner Date: Thu, 3 Oct 2024 11:00:04 +0200 Subject: [PATCH 04/14] Update projects/affiliated.md Co-authored-by: Eduardo Rodrigues --- projects/affiliated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index b02e94620..b0f37028a 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -9,7 +9,7 @@ HSF Affiliated Projects and Software *HSF Affiliated Projects and Software* are community-driven and community-oriented "endeavours" or "products" of wide and recognised interest and applicability beyond a single collaboration or experiment. -*HSF Affiliated Projects and Software* are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its remit]({{ site.baseurl }}/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no control over the endeavours/products, hence no responsibility for evolution or maintenance. +*HSF Affiliated Projects and Software* are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its goals]({{ site.baseurl }}/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no control over the endeavours/products, hence no responsibility for evolution or maintenance. Projects are in general not hosted on the HSF GitHub repository since they are externally managed and maintained, though some are on the [HSF GitHub repository](https://github.com/HSF). From b5669b26cd8fbe75083a5428e446e6a714a68d6c Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Thu, 3 Oct 2024 11:06:39 +0200 Subject: [PATCH 05/14] Update projects/affiliated.md --- projects/affiliated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index b0f37028a..8e378f17d 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -36,7 +36,7 @@ The HSF envisages a scheme for Annual Project Awards. A concrete proposal will b They are detailed in the document Guidelines for HSF Affiliated Projects and Software. -## HSF "Reviews" +## HSF Reviews The HSF can organise informal reviews of community projects upon request. Such reviews bring together a group of experts from the community to assess all aspects of a project or software, from requirements to implementation: code, packaging, documentation, etc. From 8dd2ec7e3c94575516f2480d8cb67909bab85bd1 Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Mon, 7 Oct 2024 17:39:20 +0200 Subject: [PATCH 06/14] Apply suggestions from code review --- projects/affiliated.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index 8e378f17d..83dc21962 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -3,7 +3,6 @@ title: "HSF Affiliated Projects and Software" layout: plain --- -HSF Affiliated Projects and Software ## Definitions @@ -15,7 +14,7 @@ Projects are in general not hosted on the HSF GitHub repository since they are e ## Engagement and endorsement -Any member of the community is welcome to engage with the HSF in general and the +Anyone is welcome to engage with the HSF in general and the [HSF Steering Group (SG)]({{ site.baseurl }}/organization/team.html), in particular to discuss the route towards making a software project or package an HSF Affiliated Project or Software. This can be an informal discussion initially. @@ -27,7 +26,7 @@ The recognition of bijective engagement with the HSF is displayed via *GitHub Ba Three levels distinguish mainly the level of maturity, community support and engagement: Bronze, Silver and Gold. In broad terms, the attribution of the endorsement level is based on the following guidelines, which are detailed in the dedicated document on Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Levels. * Bronze: new or young endeavour, likely evolving from and within a collaboration or experiment, but with the potential for other communities to use. It should be committed to meeting best practices in software engineering, e.g., documentation and a test suite. -* Silver: aiming for gold but in an earlier phase towards strong community support (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. +* Silver: aiming for gold but in an earlier phase towards strong community support (e.g., adoption is still modest, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. * Gold: endeavour adopted by several collaborations and/or experiments with a strong and long-term community support model. The HSF envisages a scheme for Annual Project Awards. A concrete proposal will be presented to the HSF Advisory Group once the latter is put in place. From c642268524c561ac9afa6fcd50b1dae65e72458b Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Mon, 7 Oct 2024 18:56:07 +0200 Subject: [PATCH 07/14] Update projects/affiliated.md --- projects/affiliated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index 83dc21962..9eed7b4f5 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -8,7 +8,7 @@ layout: plain *HSF Affiliated Projects and Software* are community-driven and community-oriented "endeavours" or "products" of wide and recognised interest and applicability beyond a single collaboration or experiment. -*HSF Affiliated Projects and Software* are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its goals]({{ site.baseurl }}/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no control over the endeavours/products, hence no responsibility for evolution or maintenance. +*HSF Affiliated Projects and Software* are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its goals]({{ site.baseurl }}/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no direct control over the endeavours/products, hence no responsibility for evolution or maintenance. Projects are in general not hosted on the HSF GitHub repository since they are externally managed and maintained, though some are on the [HSF GitHub repository](https://github.com/HSF). From bad071e58988962930e38af3261084375bd2b72c Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Mon, 7 Oct 2024 18:57:07 +0200 Subject: [PATCH 08/14] Update projects/affiliated.md --- projects/affiliated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index 9eed7b4f5..4d1c5c4e8 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -4,7 +4,7 @@ layout: plain --- -## Definitions +## Introduction *HSF Affiliated Projects and Software* are community-driven and community-oriented "endeavours" or "products" of wide and recognised interest and applicability beyond a single collaboration or experiment. From 454f77eb25c67980db0a8e47add2f59dadb373eb Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Tue, 8 Oct 2024 12:13:40 +0200 Subject: [PATCH 09/14] Add more suggestions from the review --- projects/affiliated.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/projects/affiliated.md b/projects/affiliated.md index 4d1c5c4e8..11453d7aa 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -6,11 +6,15 @@ layout: plain ## Introduction +The HEP Software Foundation is delighted to support and promote community software for high-energy physics. +Here we describe how we can help projects gain greater visibility and enhance the positive impact of their software. + *HSF Affiliated Projects and Software* are community-driven and community-oriented "endeavours" or "products" of wide and recognised interest and applicability beyond a single collaboration or experiment. *HSF Affiliated Projects and Software* are community projects or software packages with person-power, and possibly dedicated funding, which connect strongly to the HSF and align with [its goals]({{ site.baseurl }}/organization/goals.html). They benefit from their inclusion in, or association with, the HSF through access to the community for wide visibility and easier promotion through the network. Affiliation makes it clear that the HSF has no direct control over the endeavours/products, hence no responsibility for evolution or maintenance. -Projects are in general not hosted on the HSF GitHub repository since they are externally managed and maintained, though some are on the [HSF GitHub repository](https://github.com/HSF). +Projects are hosted on their own public platform of choice (such as GitHub); +they may use the [HSF GitHub repository](https://github.com/HSF) if desired and mutually agreed with the HSF Steering Group. ## Engagement and endorsement @@ -29,7 +33,8 @@ In broad terms, the attribution of the endorsement level is based on the followi * Silver: aiming for gold but in an earlier phase towards strong community support (e.g., adoption is still modest, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. * Gold: endeavour adopted by several collaborations and/or experiments with a strong and long-term community support model. -The HSF envisages a scheme for Annual Project Awards. A concrete proposal will be presented to the HSF Advisory Group once the latter is put in place. +The HSF envisages a scheme for Annual Project Awards. +A concrete proposal will be presented to the [HSF Advisory Group]({{ site.baseurl }}/organization/advisory-group.html) once the latter is put in place. ## Best-practice guidelines From f7587702cd53dcbe0f03a75a7615ae703da8f06c Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Tue, 8 Oct 2024 12:37:03 +0200 Subject: [PATCH 10/14] Add authors to proposal doc --- projects/affiliated.md | 1 + 1 file changed, 1 insertion(+) diff --git a/projects/affiliated.md b/projects/affiliated.md index 11453d7aa..4733151d1 100644 --- a/projects/affiliated.md +++ b/projects/affiliated.md @@ -1,5 +1,6 @@ --- title: "HSF Affiliated Projects and Software" +author: Eduardo Rodrigues, Pere Mato layout: plain --- From c142e8825a4e73bc2e2ae7e5b4be01311d13a69d Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Tue, 8 Oct 2024 12:37:52 +0200 Subject: [PATCH 11/14] Added guidelines document - WIP --- projects/guidelines.md | 155 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 projects/guidelines.md diff --git a/projects/guidelines.md b/projects/guidelines.md new file mode 100644 index 000000000..111ae2e2b --- /dev/null +++ b/projects/guidelines.md @@ -0,0 +1,155 @@ +--- +title: "Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Assignments" +author: Eduardo Rodrigues, Pere Mato +layout: plain +--- + + +In a spirit of openness and flexibility, the HSF maintains an evolving checklist of best practices for HSF Affiliated Projects and Software, rather than a set of requirements. +HSF Affiliated Projects and Software need to abide by (at least a subset of) the guidelines, +which are used for their endorsement and attribution of Bronze, Silver or Gold levels of recognition. + +The guidelines have been created to: +* Encourage projects to follow best practices; +* Help new projects discover what those practices are; and +* Help users know which projects are following best practices, meant as a guarantee of quality. + +The guidelines can be updated in light of updates or release of community practices, such as those emerging from e.g. [the EVERSE project](https://everse.software). + +The guidelines take inspiration from the “old HSF page” https://hepsoftwarefoundation.org/project_guidelines.html and from the Open Source Security Foundation (OpenSSF)’s page https://www.bestpractices.dev/en/criteria. + +## Best-practice Guidelines + +### General guidelines + +Any software library should strive to the following: +* Availability of the code in a public repository. The code should be accessible in anonymous read-only mode by anybody. GitHub is a very popular solution. +* A suitable name. It is good practice to choose a new name (a unique name is better, but often difficult) or at least a name that conveys what the library is about. Avoid pre-existing trademarks for software products or services. +* Licensing. An open-source license should be attached to the software. +* Installation. Instructions for how to install the library should be trivial to find, and the installation procedure should be standard for (e.g., at least via pip if the programming language is Python). +* Documentation. The code should be suitable documented and a users guide (at least in the format of a “quick start”) should be highlighted. For small libraries a users guide may be provided in the repository README. +* Test suite. Code should always be (comprehensively) tested. Test coverage is strongly encouraged and should be displayed on the repository for a straightforward verification of the level of testing implemented. +* Open to contributors. The repository should encourage contributions from the community and should never disable pull/merge requests on the developer platform (such as GitHub). +* Issue tracking. Each library repository provides an issue (bug, wish) tracker for users and developers to interact, allowing anonymous view of both open and closed tickets. +* General information. It is often useful if not necessary to provide extra information such as library dependencies, platforms supported, operating systems supported, etc. + +In addition, projects should consider having: +* A project website. Such a website is meant to concentrate all the information useful for users as well as developers. (Access to all sources of project information should be granted to search engine spiders.) +* Developers mailing list. A mailing list to contact developers should be made available. Better to have publicly and anonymously accessible archives and be open for subscription and posting by the public. + +### C++ specific guidelines + +This repository contains a Collaborative Collection of C++ Best Practices. +[WIP - more information will be provided in due course.] + +### Julia specific guidelines + +The Julia language documentation contains a Style Guide. +[WIP - more information will be provided in due course.] + +### Python specific guidelines + +The organisation Scientific Python provides a rather comprehensive Development Guide with a set of Topical Guides for the development and maintenance of Python libraries, which the HSF strongly encourages. These guides provide a “cookiecutter” template for the setup of a new package, and cover important topics such as packaging, code styling and documentation, testing and test coverage. + +Compliance with respect to the guidelines is provided via a “repo review” framework (GitHub repository). The review can even be done directly in a browser for repositories hosted on GitHub! + +## Endorsement Badge Levels + +Three endorsement levels are defined to distinguish mainly the level of maturity, developer support, community support and engagement: Bronze, Silver and Gold. For each level a number of requisites need to be demonstrated. Each level adds more requisites to the previous level. These requisites lay in three major categories: +Software engineering practices followed by the project (as described in the Best-practice Guideline section and with specifics for the programming language ecosystem). +Sustainability and support structures of the project (e.g. number of active developers, discussion fora, documentation, training events, time to respond to issues, etc.) +Level of adoption of the software by experiments and other projects, hence the impact of the project. + +The keywords MUST, SHOULD, MAY that appear in the criteria in this document are to be interpreted as described in RFC 2119: +The term MUST is an absolute requirement, and MUST NOT is an absolute prohibition. +The term SHOULD indicates a criterion that is normally required, but there may exist valid reasons in particular circumstances to ignore it. +The term MAY provides one way something can be done, e.g., to make it clear that the described implementation may differ and be acceptable. + +### Bronze + +The purpose of this entry level is for a young endeavour, likely evolving from and within a collaboration or experiment, but with the potential for other communities or experiments to use. At this level the category of best software practices is what is mainly required. + +#### Basics +The project SHOULD follow general and language-specific best practices as given for example in the HSF’s Best Practice Guidelines. +The project source code MUST reside on a version-controlled repository that is publicly readable and has a URL (e.g., GitHub, GitLab). +The README file at the top level MUST describe what the software does (what problem does it solve?). +The project website or repository MUST provide information on how to: obtain, provide feedback (as bug reports or enhancements), and contribute to the software. +The contribution process MUST be explained (e.g., are pull requests used?). +The software MUST be released on an Open Software license. +The project MUST post the license(s) of its results in a standard location in their source repository. + +#### Documentation + +The project MUST provide basic documentation for its software. +The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. +The project MUST have one or more mechanisms for discussion (including proposed changes and issues) that are searchable, allow messages and topics to be addressed by URL, enable new people to participate in some of the discussions, and do not require client-side installation of proprietary software. +The project MUST provide documentation in English and be able to accept bug reports and comments about code in English. + +#### Change Control + +The project's source repository MUST track what changes were made, who made the changes, and when the changes were made. +To enable collaborative review, the project's source repository SHOULD include interim versions for review between releases; it SHOULD NOT include only final releases. +The project results MUST have a unique version identifier for each release intended to be used by users. It is recommended to use Semantic Versioning. +The project MUST provide, in each release, release notes that are a human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be. The release notes MUST NOT be the raw output of a version control log (e.g., the "git log" command results are not release notes). + +#### Sustainability + +The project MUST be maintained. +The project SHOULD have at least one long-term maintainer with a contract longer than 2 years. +The project MUST provide a process for users to submit bug reports (e.g., using an issue tracker or a mailing list). +The project SHOULD use an issue tracker for tracking individual issues. +The project SHOULD acknowledge a majority of bug reports submitted in the last 2-12 months (inclusive); the response need not include a fix. +The project SHOULD respond to a majority (>50%) of enhancement requests in the last 2-12 months (inclusive). +The project MUST have a publicly available archive for reports and responses for later searching. + +#### Level of adoption + +The software produced by the project MUST be of interest for the HEP experiments. +The software SHOULD be adopted by at least one experiment. + +### Silver +Are for projects aiming for Gold but in an earlier phase towards strong community support and adoption (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. +All the criteria for Bronze MUST be fulfilled, with the addition of the following criteria. + +#### Basics + +The project MUST follow general and language-specific best practices as given for example in the HSF’s Best Practice Guidelines. + +#### Documentation +The project MUST provide different kinds of documentation: +Basic documentation. +User documentation. +Reference manual. +Tutorials (e.g. notebooks). +The project SHOULD provide specific training for users to use the software product. + +#### Sustainability +The project MUST be maintained and produce at least one new release a year if are changes and fixes that have been accumulated.. +The project MUST have at least one long-term maintainer with a contract longer than 2 years. +The project MUST use an issue tracker for tracking individual issues. +The project MUST acknowledge a majority of bug reports submitted in the last 1-3 months (inclusive); the response need not include a fix. +The project SHOULD respond to a majority (>50%) of enhancement requests in the last 1-3 months (inclusive). + +#### Level of adoption + The software MUST be adopted by at least 2 experiments/collaborations/projects. + +### Gold + +HSF endorsement level for projects that are adopted by several collaborations and/or experiments with a strong and long-term community support model. +All the criteria for Silver MUST be fulfilled, with the addition of the following criteria. + +#### Documentation + +The project MUST provide specific training for users to use the software product or tool on a frequency of once a year. +The project SHOULD organise user workshops or engage in community events as a means to collect feedback from the user community. + +#### Sustainability + +The project MUST be actively maintained and produce at least one new release a year if there are changes, and as needed patch releases to include fixes that have been accumulated. +The project MUST have at least 3 long-term maintainers with a contract longer than 2 years. +The project MUST acknowledge a majority of bug reports submitted in the last 1-4 weeks (inclusive); the response need not include a fix. +The project MUST respond to a majority (>50%) of enhancement requests in the last 1-4 weeks (inclusive). + +#### Level of adoption + +The software MUST be adopted by several (>2) large collaborations/projects and SHOULD be adopted by a number (>1) of small experiments/collaborations/projects. From 02e92d9f6ddb0e47b9d7a56b43b112baa3037b7e Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Tue, 8 Oct 2024 14:46:02 +0200 Subject: [PATCH 12/14] Added links to guidelines doc --- projects/guidelines.md | 159 +++++++++++++++++++++++------------------ 1 file changed, 89 insertions(+), 70 deletions(-) diff --git a/projects/guidelines.md b/projects/guidelines.md index 111ae2e2b..bf141b2c4 100644 --- a/projects/guidelines.md +++ b/projects/guidelines.md @@ -14,124 +14,143 @@ The guidelines have been created to: * Help new projects discover what those practices are; and * Help users know which projects are following best practices, meant as a guarantee of quality. -The guidelines can be updated in light of updates or release of community practices, such as those emerging from e.g. [the EVERSE project](https://everse.software). +The guidelines can be updated in light of updates or release of community practices, such as those emerging from e.g. the [EVERSE project](https://everse.software). + +The guidelines take inspiration from the [“old HSF page”](https://hepsoftwarefoundation.org/project_guidelines.html) and from the [Open Source Security Foundation (OpenSSF)’s page](https://www.bestpractices.dev/en/criteria). -The guidelines take inspiration from the “old HSF page” https://hepsoftwarefoundation.org/project_guidelines.html and from the Open Source Security Foundation (OpenSSF)’s page https://www.bestpractices.dev/en/criteria. ## Best-practice Guidelines ### General guidelines Any software library should strive to the following: -* Availability of the code in a public repository. The code should be accessible in anonymous read-only mode by anybody. GitHub is a very popular solution. -* A suitable name. It is good practice to choose a new name (a unique name is better, but often difficult) or at least a name that conveys what the library is about. Avoid pre-existing trademarks for software products or services. -* Licensing. An open-source license should be attached to the software. -* Installation. Instructions for how to install the library should be trivial to find, and the installation procedure should be standard for (e.g., at least via pip if the programming language is Python). -* Documentation. The code should be suitable documented and a users guide (at least in the format of a “quick start”) should be highlighted. For small libraries a users guide may be provided in the repository README. -* Test suite. Code should always be (comprehensively) tested. Test coverage is strongly encouraged and should be displayed on the repository for a straightforward verification of the level of testing implemented. -* Open to contributors. The repository should encourage contributions from the community and should never disable pull/merge requests on the developer platform (such as GitHub). -* Issue tracking. Each library repository provides an issue (bug, wish) tracker for users and developers to interact, allowing anonymous view of both open and closed tickets. -* General information. It is often useful if not necessary to provide extra information such as library dependencies, platforms supported, operating systems supported, etc. +* **Availability of the code in a public repository.** The code should be accessible in anonymous read-only mode by anybody. GitHub is a very popular solution. +* **A suitable name.** It is good practice to choose a new name (a unique name is better, but often difficult) or at least a name that conveys what the library is about. +Avoid pre-existing trademarks for software products or services. +* **Licensing.** An open-source license should be attached to the software. +* **Installation.** Instructions for how to install the library should be trivial to find, and the installation procedure should be standard for (e.g., at least via pip if the programming language is Python). +* **Documentation.** The code should be suitable documented and a users guide (at least in the format of a “quick start”) should be highlighted. For small libraries a users guide may be provided in the repository README. +* **Test suite.** Code should always be (comprehensively) tested. Test coverage is strongly encouraged and should be displayed on the repository for a straightforward verification of the level of testing implemented. +* **Open to contributors.** The repository should encourage contributions from the community and should never disable pull/merge requests on the developer platform (such as GitHub). +* **Issue tracking.** Each library repository provides an issue (bug, wish) tracker for users and developers to interact, allowing anonymous view of both open and closed tickets. +* **General information.** It is often useful if not necessary to provide extra information such as library dependencies, platforms supported, operating systems supported, etc. In addition, projects should consider having: -* A project website. Such a website is meant to concentrate all the information useful for users as well as developers. (Access to all sources of project information should be granted to search engine spiders.) -* Developers mailing list. A mailing list to contact developers should be made available. Better to have publicly and anonymously accessible archives and be open for subscription and posting by the public. +* **A project website.** Such a website is meant to concentrate all the information useful for users as well as developers. (Access to all sources of project information should be granted to search engine spiders.) +* **Developers mailing list.** A mailing list to contact developers should be made available. Better to have publicly and anonymously accessible archives and be open for subscription and posting by the public. ### C++ specific guidelines -This repository contains a Collaborative Collection of C++ Best Practices. +[This repository](https://github.com/cpp-best-practices/cppbestpractices) +contains a Collaborative Collection of C++ Best Practices. [WIP - more information will be provided in due course.] ### Julia specific guidelines -The Julia language documentation contains a Style Guide. +The Julia [language documentation](https://docs.julialang.org/) contains a Style Guide. [WIP - more information will be provided in due course.] ### Python specific guidelines -The organisation Scientific Python provides a rather comprehensive Development Guide with a set of Topical Guides for the development and maintenance of Python libraries, which the HSF strongly encourages. These guides provide a “cookiecutter” template for the setup of a new package, and cover important topics such as packaging, code styling and documentation, testing and test coverage. +The organisation [Scientific Python](https://scientific-python.org/) provides a rather comprehensiVE [Development Guide](https://learn.scientific-python.org/development/) +with a set of [Topical Guides](https://learn.scientific-python.org/development/guides/) +for the development and maintenance of Python libraries, which the HSF strongly encourages. +These guides provide a "cookiecutter" template for the setup of a new package, +and cover important topics such as packaging, code styling and documentation, testing and test coverage. -Compliance with respect to the guidelines is provided via a “repo review” framework (GitHub repository). The review can even be done directly in a browser for repositories hosted on GitHub! +Compliance with respect to the guidelines is provided via a "repo review” framework +([GitHub repository](https://github.com/scientific-python/repo-review)). +The review can even be done [directly in a browser](https://learn.scientific-python.org/development/guides/repo-review/) for repositories hosted on GitHub! ## Endorsement Badge Levels -Three endorsement levels are defined to distinguish mainly the level of maturity, developer support, community support and engagement: Bronze, Silver and Gold. For each level a number of requisites need to be demonstrated. Each level adds more requisites to the previous level. These requisites lay in three major categories: -Software engineering practices followed by the project (as described in the Best-practice Guideline section and with specifics for the programming language ecosystem). -Sustainability and support structures of the project (e.g. number of active developers, discussion fora, documentation, training events, time to respond to issues, etc.) -Level of adoption of the software by experiments and other projects, hence the impact of the project. +Three endorsement levels are defined to distinguish mainly the level of maturity, developer support, community support and engagement: Bronze, Silver and Gold. +For each level a number of requisites need to be demonstrated. +Each level adds more requisites to the previous level. +These requisites lay in three major categories: +* Software engineering practices followed by the project (as described in the Best-practice Guideline section and with specifics for the programming language ecosystem). +* Sustainability and support structures of the project (e.g. number of active developers, discussion fora, documentation, training events, time to respond to issues, etc.) +* Level of adoption of the software by experiments and other projects, hence the impact of the project. -The keywords MUST, SHOULD, MAY that appear in the criteria in this document are to be interpreted as described in RFC 2119: -The term MUST is an absolute requirement, and MUST NOT is an absolute prohibition. -The term SHOULD indicates a criterion that is normally required, but there may exist valid reasons in particular circumstances to ignore it. -The term MAY provides one way something can be done, e.g., to make it clear that the described implementation may differ and be acceptable. +The keywords *MUST*, *SHOULD*, *MAY* that appear in the criteria in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119): +* The term MUST is an absolute requirement, and MUST NOT is an absolute prohibition. +* The term SHOULD indicates a criterion that is normally required, but there may exist valid reasons in particular circumstances to ignore it. +* The term MAY provides one way something can be done, e.g., to make it clear that the described implementation may differ and be acceptable. ### Bronze The purpose of this entry level is for a young endeavour, likely evolving from and within a collaboration or experiment, but with the potential for other communities or experiments to use. At this level the category of best software practices is what is mainly required. #### Basics -The project SHOULD follow general and language-specific best practices as given for example in the HSF’s Best Practice Guidelines. -The project source code MUST reside on a version-controlled repository that is publicly readable and has a URL (e.g., GitHub, GitLab). -The README file at the top level MUST describe what the software does (what problem does it solve?). -The project website or repository MUST provide information on how to: obtain, provide feedback (as bug reports or enhancements), and contribute to the software. -The contribution process MUST be explained (e.g., are pull requests used?). -The software MUST be released on an Open Software license. -The project MUST post the license(s) of its results in a standard location in their source repository. +* The project SHOULD follow general and language-specific best practices as given for example in the HSF’s Best Practice Guidelines. +* The project source code MUST reside on a version-controlled repository that is publicly readable and has a URL (e.g., GitHub, GitLab). +* The README file at the top level MUST describe what the software does (what problem does it solve?). +* The project website or repository MUST provide information on how to: +obtain, provide feedback (as bug reports or enhancements), and contribute to the software. +* The contribution process MUST be explained (e.g., are pull requests used?). +* The software MUST be released on an Open Software license. +* The project MUST post the license(s) of its results in a standard location in their source repository. #### Documentation -The project MUST provide basic documentation for its software. -The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. -The project MUST have one or more mechanisms for discussion (including proposed changes and issues) that are searchable, allow messages and topics to be addressed by URL, enable new people to participate in some of the discussions, and do not require client-side installation of proprietary software. -The project MUST provide documentation in English and be able to accept bug reports and comments about code in English. +* The project MUST provide basic documentation for its software. +* The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. +* The project MUST have one or more mechanisms for discussion (including proposed changes and issues) that are searchable, allow messages and topics to be addressed by URL, enable new people to participate in some of the discussions, and do not require client-side installation of proprietary software. +* The project MUST provide documentation in English and be able to accept bug reports and comments about code in English. #### Change Control -The project's source repository MUST track what changes were made, who made the changes, and when the changes were made. -To enable collaborative review, the project's source repository SHOULD include interim versions for review between releases; it SHOULD NOT include only final releases. -The project results MUST have a unique version identifier for each release intended to be used by users. It is recommended to use Semantic Versioning. -The project MUST provide, in each release, release notes that are a human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be. The release notes MUST NOT be the raw output of a version control log (e.g., the "git log" command results are not release notes). +* The project's source repository MUST track what changes were made, who made the changes, and when the changes were made. +* To enable collaborative review, the project's source repository SHOULD include interim versions for review between releases; it SHOULD NOT include only final releases. +* The project results MUST have a unique version identifier for each release intended to be used by users. It is recommended to use Semantic Versioning. +* The project MUST provide, in each release, release notes that are a human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be. +The release notes MUST NOT be the raw output of a version control log (e.g., the "git log" command results are not release notes). #### Sustainability -The project MUST be maintained. -The project SHOULD have at least one long-term maintainer with a contract longer than 2 years. -The project MUST provide a process for users to submit bug reports (e.g., using an issue tracker or a mailing list). -The project SHOULD use an issue tracker for tracking individual issues. -The project SHOULD acknowledge a majority of bug reports submitted in the last 2-12 months (inclusive); the response need not include a fix. -The project SHOULD respond to a majority (>50%) of enhancement requests in the last 2-12 months (inclusive). -The project MUST have a publicly available archive for reports and responses for later searching. +* The project MUST be maintained. +* The project SHOULD have at least one long-term maintainer with a contract longer than 2 years. +* The project MUST provide a process for users to submit bug reports (e.g., using an issue tracker or a mailing list). +* The project SHOULD use an issue tracker for tracking individual issues. +* The project SHOULD acknowledge a majority of bug reports submitted in the last 2-12 months (inclusive); the response need not include a fix. +* The project SHOULD respond to a majority (>50%) of enhancement requests in the last 2-12 months (inclusive). +* The project MUST have a publicly available archive for reports and responses for later searching. #### Level of adoption -The software produced by the project MUST be of interest for the HEP experiments. -The software SHOULD be adopted by at least one experiment. +* The software produced by the project MUST be of interest for the HEP experiments. +* The software SHOULD be adopted by at least one experiment. ### Silver -Are for projects aiming for Gold but in an earlier phase towards strong community support and adoption (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). High standards of software engineering should be met. + +Are for projects aiming for Gold but in an earlier phase towards strong community support and adoption (e.g., adoption is still relatively shy, maintenance is not secured at least in the medium term by more than a single person). +High standards of software engineering should be met. All the criteria for Bronze MUST be fulfilled, with the addition of the following criteria. #### Basics -The project MUST follow general and language-specific best practices as given for example in the HSF’s Best Practice Guidelines. +* The project MUST follow general and language-specific best practices as given for example in the HSF’s Best Practice Guidelines. #### Documentation -The project MUST provide different kinds of documentation: -Basic documentation. -User documentation. -Reference manual. -Tutorials (e.g. notebooks). -The project SHOULD provide specific training for users to use the software product. + +* The project MUST provide different kinds of documentation: + - Basic documentation. + - User documentation. + - Reference manual. + - Tutorials (e.g. notebooks). + - The project SHOULD provide specific training for users to use the software product. #### Sustainability -The project MUST be maintained and produce at least one new release a year if are changes and fixes that have been accumulated.. -The project MUST have at least one long-term maintainer with a contract longer than 2 years. -The project MUST use an issue tracker for tracking individual issues. -The project MUST acknowledge a majority of bug reports submitted in the last 1-3 months (inclusive); the response need not include a fix. -The project SHOULD respond to a majority (>50%) of enhancement requests in the last 1-3 months (inclusive). + +* The project MUST be maintained and produce at least one new release a year if are changes and fixes that have been accumulated.. +* The project MUST have at least one long-term maintainer with a contract longer than 2 years. +* The project MUST use an issue tracker for tracking individual issues. +* The project MUST acknowledge a majority of bug reports submitted in the last 1-3 months (inclusive); the response need not include a fix. +* The project SHOULD respond to a majority (>50%) of enhancement requests in the last 1-3 months (inclusive). #### Level of adoption - The software MUST be adopted by at least 2 experiments/collaborations/projects. + +* The software MUST be adopted by at least 2 experiments/collaborations/projects. ### Gold @@ -140,16 +159,16 @@ All the criteria for Silver MUST be fulfilled, with the addition of the followin #### Documentation -The project MUST provide specific training for users to use the software product or tool on a frequency of once a year. -The project SHOULD organise user workshops or engage in community events as a means to collect feedback from the user community. +* The project MUST provide specific training for users to use the software product or tool on a frequency of once a year. +* The project SHOULD organise user workshops or engage in community events as a means to collect feedback from the user community. #### Sustainability -The project MUST be actively maintained and produce at least one new release a year if there are changes, and as needed patch releases to include fixes that have been accumulated. -The project MUST have at least 3 long-term maintainers with a contract longer than 2 years. -The project MUST acknowledge a majority of bug reports submitted in the last 1-4 weeks (inclusive); the response need not include a fix. -The project MUST respond to a majority (>50%) of enhancement requests in the last 1-4 weeks (inclusive). +* The project MUST be actively maintained and produce at least one new release a year if there are changes, and as needed patch releases to include fixes that have been accumulated. +* The project MUST have at least 3 long-term maintainers with a contract longer than 2 years. +* The project MUST acknowledge a majority of bug reports submitted in the last 1-4 weeks (inclusive); the response need not include a fix. +* The project MUST respond to a majority (>50%) of enhancement requests in the last 1-4 weeks (inclusive). #### Level of adoption -The software MUST be adopted by several (>2) large collaborations/projects and SHOULD be adopted by a number (>1) of small experiments/collaborations/projects. +* The software MUST be adopted by several (>2) large collaborations/projects and SHOULD be adopted by a number (>1) of small experiments/collaborations/projects. From fee193cf2bd9fda34c16cd603d0a950e6fdd02f3 Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues Date: Tue, 8 Oct 2024 14:47:31 +0200 Subject: [PATCH 13/14] Add links to these 2 new documents to the navbar --- _includes/navbar.ext | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_includes/navbar.ext b/_includes/navbar.ext index ab49fc999..6ce5f53e2 100644 --- a/_includes/navbar.ext +++ b/_includes/navbar.ext @@ -56,9 +56,11 @@
  •   Projects & Support
    • From c81fa5a7e2d22cf7c155e2a57560df1635c13373 Mon Sep 17 00:00:00 2001 From: Graeme A Stewart Date: Tue, 8 Oct 2024 22:13:12 +0200 Subject: [PATCH 14/14] Fix navbar and shorten page title --- _includes/navbar.ext | 4 ++-- projects/guidelines.md | 4 +--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/_includes/navbar.ext b/_includes/navbar.ext index 6ce5f53e2..1c7a74686 100644 --- a/_includes/navbar.ext +++ b/_includes/navbar.ext @@ -56,8 +56,8 @@
  •   Projects & Support
      -
    • HSF Affiliated Projects and Software
      • -
    • Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Assignments
      • +
    • HSF Affiliated Projects and Software
      • +
    • Projects and Software Guidelines
    • How to join as a project
    • Member Projects
      • diff --git a/projects/guidelines.md b/projects/guidelines.md index bf141b2c4..ed796d690 100644 --- a/projects/guidelines.md +++ b/projects/guidelines.md @@ -1,10 +1,9 @@ --- -title: "Guidelines for HSF Affiliated Projects and Software, and Endorsement Badge Assignments" +title: "Affiliated Projects and Software Guidelines" author: Eduardo Rodrigues, Pere Mato layout: plain --- - In a spirit of openness and flexibility, the HSF maintains an evolving checklist of best practices for HSF Affiliated Projects and Software, rather than a set of requirements. HSF Affiliated Projects and Software need to abide by (at least a subset of) the guidelines, which are used for their endorsement and attribution of Bronze, Silver or Gold levels of recognition. @@ -18,7 +17,6 @@ The guidelines can be updated in light of updates or release of community practi The guidelines take inspiration from the [“old HSF page”](https://hepsoftwarefoundation.org/project_guidelines.html) and from the [Open Source Security Foundation (OpenSSF)’s page](https://www.bestpractices.dev/en/criteria). - ## Best-practice Guidelines ### General guidelines