nlesc-jcer / qmcflow Goto Github PK

By enabling Zenodo integration, your package will automatically get a DOI which can be used to cite your package. After enabling Zenodo integration for your GitHub repository, Zenodo will create a snapshot and archive each release you make on GitHub. Moreover, Zenodo will create a new DOI for each GitHub release of your code.

To enable Zenodo integration:

1. Go to http://zenodo.org and login with your GitHub account. When you are redirected to GitHub, Authorize application to give permission to Zenodo to access your account.
2. Go to https://zenodo.org/account/settings/github/ and enable Zenodo integration of your repository by clicking on On toggle button.
3. Your package will get a DOI only after you make a release. Create a new release as described in README.dev.md
4. At this point you should have a DOI. To find out the DOI generated by Zenodo:
   1. Visit https://zenodo.org/deposit and click on your repository link
   2. You will find the latest DOI in the right column in Versions box in Cite all versions? section
   3. Copy the text of the link. For example 10.5281/zenodo.1310751
5. Update the badge in your repository

   1. Edit README.md and replace the badge placeholder with the badge link you copied in previous step.
      The badge placeholder is shown below.

      [![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>)

For FAQ about Zenodo please visit https://help.zenodo.org/.

It is likely that your CITATION.cff currently doesn't pass validation. The error messages you get from the cffconvert GitHub Action are unfortunately a bit cryptic, but doing the following helps:

• Check if the given-name and family-name keys need updating. If your family name has a name particle like von or van or de, use the name-particle key; if your name has a suffix like Sr or IV, use name-suffix. For details, refer to the schema description: https://github.com/citation-file-format/citation-file-format
• Update the value of the orcid key. If you do not have an orcid yet, you can get one here https://orcid.org/.
• Add more authors if needed
• Update date-released using the YYYY-MM-DD format.
• Update the doi key with the conceptDOI for your repository (see https://help.zenodo.org for more information on what a conceptDOI is). If your project doesn't have a DOI yet, you can use the string 10.0000/FIXME to pass validation.
• Verify that the keywords array accurately describes your project.

Once you do all the steps above, the cffconvert workflow will tell you what content it expected to see in .zenodo.json. Copy-paste from the GitHub Action log into a new file .zenodo.json. Afterwards, the cffconvert GitHub Action should be green.

To help you keep the citation metadata up to date and synchronized, the cffconvert GitHub Action checks the following 6 aspects:

1. Whether your repository includes a CITATION.cff file.

   By including this file, authors of the software can receive credit for the work they put in.

2. Whether your CITATION.cff is valid YAML.

   Visit http://www.yamllint.com/ to see if the contents of your CITATION.cff are valid YAML.

3. Whether your CITATION.cff adheres to the schema (as listed in the CITATION.cff file itself under key cff-version).

   The Citation File Format schema can be found here, along with an explanation of all the keys. You're advised to use the latest available schema version.

4. Whether your repository includes a .zenodo.json file.

   With this file, you can control what metadata should be associated with any future releases of your software on Zenodo: things like the author names, along with their affiliations and their ORCIDs, the license under which the software has been released, as well as the name of your software and a short description. If your repository doesn't have a .zenodo.json file, Zenodo will take a somewhat crude guess to assign these metadata.

   The cffconvert GitHub action will tell you what it expects to find in .zenodo.json, just copy and paste it to a new file named .zenodo.json. The suggested text ignores CITATION.cff's version, commit, and date-released. cffconvert considers these keys suspect in the sense that they are often out of date, and there is little purpose to telling Zenodo about these properties: Zenodo already knows.

5. Whether .zenodo.json is valid JSON.

   Currently unimplemented, but you can check for yourself on https://jsonlint.com/.

6. Whether CITATION.cff and .zenodo.json contain equivalent data.

   This final check verifies that the two files are in sync. The check ignores CITATION.cff's version, commit, and date-released.

By enabling Zenodo integration, your package will automatically get a DOI which can be used to cite your package. After enabling Zenodo integration for your GitHub repository, Zenodo will create a snapshot and archive each release you make on GitHub. Moreover, Zenodo will create a new DOI for each GitHub release of your code.

To enable Zenodo integration:

1. Go to http://zenodo.org and login with your GitHub account. When you are redirected to GitHub, Authorize application to give permission to Zenodo to access your account.
2. Go to https://zenodo.org/account/settings/github/ and enable Zenodo integration of your repository by clicking on On toggle button.
3. Your package will get a DOI only after you make a release. Create a new release as described in README.dev.md
4. At this point you should have a DOI. To find out the DOI generated by Zenodo:
   1. Visit https://zenodo.org/deposit and click on your repository link
   2. You will find the latest DOI in the right column in Versions box in Cite all versions? section
   3. Copy the text of the link. For example 10.5281/zenodo.1310751
5. Update the badge in your repository

   1. Edit README.md and replace the badge placeholder with the badge link you copied in previous step.
      The badge placeholder is shown below.

      [![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>)

For FAQ about Zenodo please visit https://help.zenodo.org/.

Continuous code quality can be handled by Sonarcloud. This repository is configured to use Sonarcloud to perform quality analysis and code coverage report on each push.

In order to configure Sonarcloud analysis GitHub Action workflow you must follow the steps below:

1. go to Sonarcloud to create a new Sonarcloud project
2. login with your GitHub account
3. add Sonarcloud organization or reuse existing one
4. set up a repository
5. go to new code definition administration page and select Number of days option
6. To be able to run the analysis:
   1. a token must be created at Sonarcloud account
   2. the created token must be added as SONAR_TOKEN to secrets on GitHub

Your repository has a workflow which lints your code after every push and when creating a pull request.

Linter workflow may fail if description or keywords field in setup.cfg is empty. Please update these fields. To validate your changes run:

prospector

Enabling githook will automatically lint your code in every commit. You can enable it by running the command below.

git config --local core.hooksPath .githooks

Your Python package should have publicly available documentation, including API documentation for your users.
Read the Docs can host your user documentation for you.

To host the documentation of this repository please perform the following instructions:

1. go to Read the Docs
2. log in with your GitHub account
3. find NLESC-JCER/qmcflow in list and press + button.
   • If repository is not listed,
     1. go to Read the Docs GitHub app
     2. make sure NLESC-JCER has been granted access.
     3. reload repository list on Read the Docs import page
4. wait for the first build to be completed at https://readthedocs.org/projects/qmcflow/builds
5. check that the link of the documentation badge in the README.md works

See README.dev.md# how to build documentation site locally.

Continuous code quality can be handled by Sonarcloud. This repository is configured to use Sonarcloud to perform quality analysis and code coverage report on each push.

In order to configure Sonarcloud analysis GitHub Action workflow you must follow the steps below:

1. go to Sonarcloud to create a new Sonarcloud project
2. login with your GitHub account
3. add Sonarcloud organization or reuse existing one
4. set up a repository
5. go to new code definition administration page and select Number of days option
6. To be able to run the analysis:
   1. a token must be created at Sonarcloud account
   2. the created token must be added as SONAR_TOKEN to secrets on GitHub

Your Python package should have publicly available documentation, including API documentation for your users.
Read the Docs can host your user documentation for you.

To host the documentation of this repository please perform the following instructions:

1. go to Read the Docs
2. log in with your GitHub account
3. find NLESC-JCER/qmcflow in list and press + button.
   • If repository is not listed,
     1. go to Read the Docs GitHub app
     2. make sure NLESC-JCER has been granted access.
     3. reload repository list on Read the Docs import page
4. wait for the first build to be completed at https://readthedocs.org/projects/qmcflow/builds
5. check that the link of the documentation badge in the README.md works

See README.dev.md# how to build documentation site locally.

It is likely that your CITATION.cff currently doesn't pass validation. The error messages you get from the cffconvert GitHub Action are unfortunately a bit cryptic, but doing the following helps:

• Check if the given-name and family-name keys need updating. If your family name has a name particle like von or van or de, use the name-particle key; if your name has a suffix like Sr or IV, use name-suffix. For details, refer to the schema description: https://github.com/citation-file-format/citation-file-format
• Update the value of the orcid key. If you do not have an orcid yet, you can get one here https://orcid.org/.
• Add more authors if needed
• Update date-released using the YYYY-MM-DD format.
• Update the doi key with the conceptDOI for your repository (see https://help.zenodo.org for more information on what a conceptDOI is). If your project doesn't have a DOI yet, you can use the string 10.0000/FIXME to pass validation.
• Verify that the keywords array accurately describes your project.

Once you do all the steps above, the cffconvert workflow will tell you what content it expected to see in .zenodo.json. Copy-paste from the GitHub Action log into a new file .zenodo.json. Afterwards, the cffconvert GitHub Action should be green.

To help you keep the citation metadata up to date and synchronized, the cffconvert GitHub Action checks the following 6 aspects:

1. Whether your repository includes a CITATION.cff file.

   By including this file, authors of the software can receive credit for the work they put in.

2. Whether your CITATION.cff is valid YAML.

   Visit http://www.yamllint.com/ to see if the contents of your CITATION.cff are valid YAML.

3. Whether your CITATION.cff adheres to the schema (as listed in the CITATION.cff file itself under key cff-version).

   The Citation File Format schema can be found here, along with an explanation of all the keys. You're advised to use the latest available schema version.

4. Whether your repository includes a .zenodo.json file.

   With this file, you can control what metadata should be associated with any future releases of your software on Zenodo: things like the author names, along with their affiliations and their ORCIDs, the license under which the software has been released, as well as the name of your software and a short description. If your repository doesn't have a .zenodo.json file, Zenodo will take a somewhat crude guess to assign these metadata.

   The cffconvert GitHub action will tell you what it expects to find in .zenodo.json, just copy and paste it to a new file named .zenodo.json. The suggested text ignores CITATION.cff's version, commit, and date-released. cffconvert considers these keys suspect in the sense that they are often out of date, and there is little purpose to telling Zenodo about these properties: Zenodo already knows.

5. Whether .zenodo.json is valid JSON.

   Currently unimplemented, but you can check for yourself on https://jsonlint.com/.

6. Whether CITATION.cff and .zenodo.json contain equivalent data.

   This final check verifies that the two files are in sync. The check ignores CITATION.cff's version, commit, and date-released.

Your repository has a workflow which lints your code after every push and when creating a pull request.

Linter workflow may fail if description or keywords field in setup.cfg is empty. Please update these fields. To validate your changes run:

prospector

Enabling githook will automatically lint your code in every commit. You can enable it by running the command below.

git config --local core.hooksPath .githooks