From 12837eb48c24a84eab2d99ac03f9cf720ec742fc Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Tue, 9 Apr 2024 08:08:18 -0600 Subject: [PATCH] Update README --- README.md | 364 +++++++++--------- make_paper.sh | 17 - publisher/README.md | 45 ++- publisher/getting_ready_for_new_year.md | 51 ++- .../requirements.txt | 0 pull_request_template.md | 10 +- 6 files changed, 239 insertions(+), 248 deletions(-) delete mode 100755 make_paper.sh rename requirements.txt => publisher/requirements.txt (100%) diff --git a/README.md b/README.md index 94438c97cb..5404c78906 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,15 @@ You can find the [schedule for 2024](#timeline-for-2024) below. Please use @-mentions in issues and pull requests(PRs) to [contact the proceedings Co-Chairs](#contacting-the-proceedings-co-chairs). -If you are an *Author*, please see [Instructions for Authors](#instructions-for-authors). +If you are an _Author_, please see [Instructions for Authors](#instructions-for-authors). -If you are a *Reviewer*, please see [Instructions for Reviewers](#instructions-for-reviewers). +If you are a _Reviewer_, please see [Instructions for Reviewers](#instructions-for-reviewers). -If you are an *Editor*, please see [Instructions for Editors](#instructions-for-editors). +If you are an _Editor_, please see [Instructions for Editors](#instructions-for-editors). -If you are a *Publisher*, please see [Instructions for Publishers](#instructions-for-publishers). +If you are a _Publisher_, please see [Instructions for Publishers](#instructions-for-publishers). -If you are *Submitting Slides*, please see [Instructions for Slides](#instructions-for-slides). +If you are _Submitting Slides_, please see [Instructions for Slides](#instructions-for-slides). ## Organising Principles: Openness @@ -39,73 +39,57 @@ The technologies used for running the conference are themselves developed in the open and built on open source tools. Open Development: + - with many people contributing code over more than a decade - - many contributors start as authors submitting to the proceedings - - provides a natural pathway for new members to join the proceedings committee -- technologies are managed via public, open source GitHub repositories: - - build system: https://github.com/scipy-conference/scipy_proceedings - - server: https://github.com/scipy-conference/procbuild - -The systems for running the conference are built on top of open source tools: -- build system: - - LaTeX - - ReStructured Text (reST) - - Python: docutils, lxml, pygments, pytest -- server: - - Flask & waitress - - pyzmq - - Docker - - Python: asyncio + - many contributors start as authors submitting to the proceedings + - provides a natural pathway for new members to join the proceedings committee +- technologies are managed via public, open source GitHub repositories + +The systems for running the conference are built on top of open source tools, including: + +- MyST Markdown ([mystmd.org](https://mystmd.org)) +- Typst - for fast PDF generation ### Open Peer Review meets Open Source Code Review The entire submission and review procedure occurs through public PRs attached to identifiable individuals. -- Authors and reviewers are encouraged to work collaboratively to improve - submissions throughout the review process, much like open source code-review. +- Authors and reviewers are encouraged to work collaboratively to improve submissions throughout the review process, much like open source code-review. -- Reviews are collaborative, aiming to improve the publication quality. This is - possible because the content was already vetted by the program committee. +- Reviews are collaborative, aiming to improve the publication quality. This is possible because the content was already vetted by the program committee. -- Conversations occur attached to people's real GitHub usernames and are open to - the public. - - This allows for a transparent open review process. - - This holds authors and reviewers accountable and encourages civil communication practices. +- Conversations occur attached to people's real GitHub usernames and are open to the public. + - This allows for a transparent open review process. + - This holds authors and reviewers accountable and encourages civil communication practices. ### Open Access for an Open Community -The papers are published as true Open Access (OA) articles with Creative Commons -Attribution (CC By) license. +The papers are published as true Open Access (OA) articles with Creative Commons Attribution ([CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)) license. - There are no article processing charges barring authors from submitting papers. - - Reviewers and co-chairs volunteer their time. - - Services with free tiers (like GitHub and Heroku) allow distributing the - underlying technologies with minimal cost. -- Papers are openly available at http://conference.scipy.org/proceedings/, with - no pay walls barring consumption or author processing charges. + - Reviewers and co-chairs volunteer their time. + - Services with free tiers (like GitHub) allow distributing the underlying technologies with minimal cost. + +- Papers are openly available at http://proceedings.scipy.org, with no pay walls barring consumption or author processing charges. -- From 2010 onward, papers have DOIs (making them easily citable) and are also - openly available from those DOIs. +- From 2010 onward, papers have DOIs (making them easily citable) and are also openly available from those DOIs. -The community is involved in the entire process for creating the proceedings, -which ensures relevance to the community that created them. +- From 2023 onwards, full HTML is the _preferred_ format in addition to the PDF being available. -- Papers are submitted by authors who will be presenting talks and posters at the - annual SciPy conference. Because we know the content is relevant to the SciPy - community, review can focus on improving papers, not vetting them. +The community is involved in the entire process for creating the proceedings, which ensures relevance to the community that created them. -- Reviewers are invited by the editors, but community members may volunteer to - review papers that interest them. The only barrier to participation is having - a GitHub account. +- Papers are submitted by authors who will be presenting talks and posters at the annual SciPy conference. Because we know the content is relevant to the SciPy community, review can focus on improving papers, not vetting them. +- Reviewers are invited by the editors, but community members may volunteer to review papers that interest them. The only barrier to participation is having a GitHub account. ## Contacting the Proceedings Co-Chairs The most effective way to contact the Proceedings Co-Chairs for issues related to this GitHub repository is to use GitHub's issues and "@"-mentioning the Co-Chairs. -In 2024, the Proceedings Co-Chairs are +In 2024, the Proceedings Co-Chairs are: + - Meghann Agarwal (@mepa) - Amey Ambade (@ameyxd) - Chris Calloway (@cbcunc) @@ -132,10 +116,15 @@ In addition to the following list, we break up the deadlines in the respective d ## Instructions for Authors -Please submit your papers by 23:59 PST of the *1st Draft for Submission* -Deadline. +Please submit your papers by 23:59 PST of the _1st Draft for Submission_ Deadline. -Submit your papers as a reStructuredText (rst) or LaTeX file via PR against this repository. Supporting LaTeX submissions is very new this year, so please consider it to be in beta, and please only use this option if you are already familiar with writing papers in LaTeX. +Submit your papers as a MyST Markdown ([mystmd.org](https://mystmd.org)) or +LaTeX file via PR against this repository. +Please only use LaTeX if you are already familiar with writing papers in LaTeX. +The build process are using the `mystmd` CLI in 2024, which allows us to support +a web-first reading experience. +In future years this will allow us to accept notebooks and computational +environments, however, this is not available in 2024. During the Open Review Period authors should work with their reviewers to refine and improve their submission. @@ -158,6 +147,12 @@ In the event that authors and reviewers are deadlocked, they should alert the Proceedings Co-Chairs to this situation. As always, the Proceedings Co-Chairs have final say in whether to accept or reject a paper. +### Getting Help + +If you have a challenge with any technical aspect of authoring your paper in MyST or LaTeX, +please do not hesitate to reach out via your GitHub pull request or issue on this repository. +A member of the Proceedings Co-chairs will help you directly or identify a work-around. + ### Author Deadlines - Apr 19: Authors invited to submit full papers @@ -166,34 +161,33 @@ have final say in whether to accept or reject a paper. - Jul 31: Final Author Revision Deadline - Aug 9: Final Editorial Decisions for Proceedings Contents Deadline -### General Information and Guidelines for Authors: - -- Papers are formatted using reStructuredText. -- Example papers are provided in `papers/00_bibderwalt` and `papers/00_vanderwalt`. - - These papers provide examples of how to: - - Label figures, equations and tables - - Use math markup - - Include code snippets - - `00_bibderwalt` shows how to use a bib file for citations. -- For your paper to be found by the build system at http://procbuild.scipy.org - your PR needs to have a title that begins with "Paper:". If you do not do - this, the co-chairs will change your title on your behalf. +### General Information and Guidelines for Authors + +- Papers are formatted using MyST ([mystmd.org](https://mystmd.org)) or LaTeX (please see notes on LaTeX below) +- The paper is written and reviewed using the interactive HTML view (i.e. `myst start`), the PDF is built upon acceptance only +- Example papers are provided in `papers/00_bibderwalt` and `papers/00_vanderwalt` + - These papers provide examples of how to: + - Label figures, equations and tables + - Use math markup + - Include code snippets + - Use a BibTeX files and/or DOIs for citations +- When creating your pull-request, add a pull-request label of `paper` to trigger the build process. If you do not add this, a proceedings chair member will add it for you. - Authors may include a project or consortium (e.g. [The Jupyter Project](https://raw.githubusercontent.com/scipy-conference/scipy_proceedings/2018/papers/project_jupyter/paper.rst)) - There must be at least one corresponding author, and this must be a specific person with a valid email address - Authors of papers from previous SciPys may change their name on their published work by contacting the Proceedings Co-chairs -- All citations that have DOIs should include those DOIs in the paper's - references section, see [`mybib.bib`](./papers/00_bibderwalt/mybib.bib). +- All citations that have DOIs should include those DOIs in the paper's references section, see [`mybib.bib`](./papers/00_bibderwalt/mybib.bib). - All figures and tables should have captions. -- Figures and tables should be positioned inline, close to their explanatory text. +- Figures and tables should be positioned close to their explanatory text. +- All abbreviations should be identified in your `myst.yml` ([docs](https://mystmd.org/guide/glossaries-and-terms#abbreviations)) - License conditions on images and figures must be respected (Creative Commons, - etc.). -- Images and figures should be reasonably sized and formatted for viewing online; typically a few hundred kilobytes and less than 1 MB. -- Code snippets should be formatted to fit inside a single column without - overflow. -- Avoid custom LaTeX markup where possible. -- Do not modify any files outside of your paper directory. -- The compiled version of the paper (PDF) should be at most 8 pages, - including figures but not including references. + etc.) +- Images and figures should be reasonably sized and formatted for viewing online; typically less than 1 MB +- Do not modify any files outside of your paper directory +- When using the LaTeX option, please consider: + - We are supporting _HTML_. LaTeX is not involved in reading or rendering (as of 2024 we use Typst) + - Custom LaTeX macros are **not** supported and some packages may not be supported +- The compiled version of the paper should be at most XXX words + including figures but not including references; this is about 8 pages for the published PDF that will be created upon acceptance. ### Author Workflow @@ -222,13 +216,13 @@ git clone https://github.com/mpacer/scipy_proceedings 1. Get a local copy of the `scipy_proceedings` repo. 2. Update your local copy of the `scipy_proceedings` repo. 3. [Create a new branch](#creating-a-new-branch) for your paper based off the latest `2024` branch. - - If you submit multiple papers, you will need a new branch for each. -4. [Set up your environment](#setting-up-your-environment). -5. [Write your paper](#write-your-paper), [commit changes](#commit-your-changes), and [build your paper](#build-your-paper) -6. [Create a PR](#create-a-paper-pr) or [push changes to your PR's branch](#push-your-changes) and [check your paper](#check-your-paper) on http://procbuild.scipy.org. - - If you want to alter the build system, do not include it in your - submission's PR, create a separate PR against `dev` - ([see below](#creating-build-system-prs) for more details). + - If you submit multiple papers, you will need a new branch for each. +4. [Install MyST Markdown and Node](#setting-up-your-environment). +5. [Write your paper](#write-your-paper), [commit changes](#commit-your-changes), and [build your paper](#preview-your-paper) +6. [Create a PR](#create-a-paper-pr) or [push changes to your PR's branch](#push-your-changes) and [check your paper](#check-your-paper). + - If you want to alter the build system, do not include it in your + submission's PR, create a separate PR against `dev` + ([see below](#creating-build-system-prs) for more details). 7. Repeat steps 5 and 6, while also responding to reviewer feedback. #### Getting a local copy of the scipy_proceedings repo @@ -238,12 +232,13 @@ git clone https://github.com/mpacer/scipy_proceedings [scipy_proceedings](https://github.com/scipy-conference/scipy_proceedings) repository on GitHub. - Clone the repo locally - - `git clone https://github.com//scipy_proceedings` - - `cd scipy_proceedings/` + - `git clone https://github.com//scipy_proceedings` + - `cd scipy_proceedings/` - Add the `scipy-conference` repository as your `upstream` remote - - `git remote add upstream https://github.com/scipy-conference/scipy_proceedings` + - `git remote add upstream https://github.com/scipy-conference/scipy_proceedings` If you run `git remote -v ` you should see something like the following: + ``` origin https://github.com//scipy_proceedings.git (fetch) origin https://github.com//scipy_proceedings.git (push) @@ -254,9 +249,9 @@ upstream https://github.com/scipy-conference/scipy_proceedings.git (push) #### Getting the latest branch - Fetch the latest version of the `scipy_proceedings` repo - - `git fetch upstream` + - `git fetch upstream` - Check out the upstream `2024` branch - - `git checkout -b 2024 --track upstream/2024` + - `git checkout -b 2024 --track upstream/2024` #### Creating a new branch @@ -273,65 +268,73 @@ git push --set-upstream origin #### Setting up your environment -- Create a new environment (using your choice of environment manager, e.g., `pyenv` or `conda`). -- Install/update the required python libraries (`pip install -U -r requirements.txt`). -- Install LaTeX and any other non-python dependencies +- _Optional_: Create a new environment (using your choice of environment manager, e.g., `pyenv` or `conda`). +- Install MyST Markdown from [mystmd.org](https://mystmd.org/guide/quickstart) + - `pip install mystmd` + - Install `nodejs` (see [options](https://mystmd.org/guide/installing-prerequisites)) - Create a new directory `papers/` - - if you are submitting one paper, we recommend you use `` - - if you are submitting more than one paper, you will need to use a different - directory name for each paper + - if you are submitting one paper, we recommend you use `` + - if you are submitting more than one paper, you will need to use a different + directory name for each paper #### Write your paper -- Copy an example paper into your directory. - - You must have only one reST file in the top level of ``. -- As you make changes to your paper, commit those changes in discrete chunks. +- Copy an example paper into your directory + - Update the `id` in the `myst.yml` to by `scipy-2024-` + - Update the author information and affiliations in `myst.yml` + - The templates are setup for a _single_ MyST/LaTeX file in the top level of `` + - If you have more than one file run `myst init --write-toc` ([docs](https://mystmd.org/guide/table-of-contents)), ensuring that the `root` is the main file of your manuscript +- To preview your changes, run `myst start` and open the web-server provided +- Refer to the syntax in the template papers or online at [mystmd.org](https://mystmd.org/guide/) +- As you make changes to your paper, commit those changes in discrete chunks +- If you come across any challenges, ask the Proceedings Co-chairs for help via a GitHub issue or comment on your PR #### Commit your changes -- Commit any changes inside the `paper/` -- When you push your commits to your PR's branch, the paper will be autobuilt -- Do not commit any changes to files outside of your paper directory. +- Commit any changes inside the `papers/` +- When you push your commits to your PR's branch, the paper will be auto-built in GitHub actions +- Do not commit any changes to files outside of your paper directory If you want to change the way the build system works, we use a separate submission procedure ([see below](#creating-build-system-prs)). -#### Build your paper +#### Preview your paper + +Your paper will be **edited and reviewed in HTML**, the PDF will only be built on acceptance. -- Run `./make_paper.sh papers/firstname_surname` to make a PDF of your paper -- Check the output in `output//paper.pdf`. -- Check that this output matches what you see on the - [build server](http://procbuild.scipy.org). +To preview your paper: + +- Ensure `mystmd` is installed ([guide](https://mystmd.org/guide/quickstart)) +- In `papers/` run `myst start` +- Open the web-server from your console +- Check that this output matches what is built on your PR #### Create a paper PR -- Once you are ready to submit your paper, make a pull request on GitHub. - **Please ensure that you file against the correct branch.** -- Create a pull request against our `2024` branch. +Once you are ready to submit your paper, make a pull request on GitHub. **Please ensure that you file against the correct branch.** + +- Create a pull request against the `2024` branch - Do not modify any files outside of your paper directory. Create a separate PR for any changes to the build system. +- Ensure that your PR has a `paper` label, if not, one will be added for you #### Creating build system PRs -If you want to change the way the build system works, we use a separate -submission procedure. +If you want to change the way the build system works, the documentation, etc., we use a separate submission procedure. -- Create a new branch against `dev`. -- Make your changes to the build system. -- Do **not** commit any changes from your paper PR to this new branch. -- Make a separate PR against the `dev` branch, it will be reviewed separately. +- Create a new branch against `dev` +- Make your changes to the build system +- Do **not** commit any changes from your paper PR to this new branch +- Make a separate PR against the `dev` branch, it will be reviewed separately #### Push to your PR -When you push to your repositories branch it automatically updates the PR. This -triggers a new build on the provided [build server](http://procbuild.scipy.org). +When you push to your repositories branch it automatically run GitHub actions on the PR. +Note that this will require authorization for your first commit only. +The build process takes about a minute, and then posts or updates a comment on the PR with a link to the build result on Curvenote. The build page has a link to your preview. #### Check your paper's build -We encourage reviewers to review the PDFs built on our -[build server](http://procbuild.scipy.org). - -You should regularly check to see if the paper(s) that you build locally match the -paper(s) that you see on the server. +The review process will be completed on the HTML, and you can check to see if the paper(s) that you preview locally match the paper(s) that you see online. These will be available in a GitHub comment or through the logs in the GitHub action. If it is not the same, please immediately contact us with a GitHub issue describing the discrepancy. Please include screenshots and an explanation of the @@ -340,7 +343,7 @@ differences. For best results, please [@-mention the Proceedings Co-Chairs](#con ## Instructions for Reviewers You will be reviewing authors' pull requests. While authors should have a proper -draft of their paper ready for you by *1st Draft Submission* deadline. +draft of their paper ready for you by _1st Draft Submission_ deadline. We ask that you read [this set of suggested review criteria](https://github.com/scipy-conference/scipy_proceedings/blob/2024/review_criteria.md) before beginning any reviews. @@ -351,19 +354,19 @@ working on. Our aim is to have you and the author collaborate on making their better by using an iterative process. While our basic approach is to have you and the author iterate, we ask you to -complete an initial review and start that conversation by the *Initial Complete Review -Deadline*. +complete an initial review and start that conversation by the _Initial Complete Review +Deadline_. -We ask that by the *Final Recommendation Deadline* you have a recommendation to +We ask that by the _Final Recommendation Deadline_ you have a recommendation to either **accept** or **reject** the paper at that point and time. **Note**: -You many recommend changes after the *Final Recommendation Deadline*. If there -are any major changes after the *Final Recommendation Deadline* you should +You many recommend changes after the _Final Recommendation Deadline_. If there +are any major changes after the _Final Recommendation Deadline_ you should immediately contact the Proceedings Committee Co-Chairs. As a heuristic, if you think the paper should not be in the proceedings unless the authors make the change in question, then that change should be requested and made before the -*Final Recommendation Deadline*. +_Final Recommendation Deadline_. ### Reviewer Deadlines @@ -377,17 +380,18 @@ change in question, then that change should be requested and made before the - Read [this set of suggested review criteria](https://github.com/scipy-conference/scipy_proceedings/blob/2024/review_criteria.md) - Click on the Pull Requests Tab and find the papers assigned to you -- After reading the paper, you can start the review conversation however you prefer - - You can use line comments (on the paper itself) or high-level comments. +- A comment at the top of the PR will have a link to the paper to review online +- After reading the paper online, you can start the review conversation however you prefer + - You can use in-line comments (on the paper itself) or high-level comments. - Authors will respond to your comments, possibly via their own comments or by modifying their paper. - This begins an iterative review process where authors and reviewers can discuss the evolving submission. -- By the *Final Recommendation Deadline*, we ask that you give two things - 1. A comprehensive review of the paper as it stands. This will act as the final - review. - 2. A final recommendation to include the paper in the proceedings or not. - - When you make the Final Recommendation, please [contact the proceedings Co-Chairs](#contacting-the-proceedings-co-chairs) in the PR in question. +- By the _Final Recommendation Deadline_, we ask that you give two things + 1. A comprehensive review of the paper as it stands. This will act as the final + review. + 2. A final recommendation to include the paper in the proceedings or not. + - When you make the Final Recommendation, please [contact the proceedings Co-Chairs](#contacting-the-proceedings-co-chairs) in the PR in question. ## Review Criteria @@ -396,43 +400,21 @@ A small subcommittee of the SciPy 2017 organizing committee has created to help guide authors and reviewers alike. Suggestions and amendments to these review criteria are enthusiastically welcomed via discussion or pull request. - ## Requirements - - Install the requirements in the requirements.txt file: `pip install -r requirements.txt` - - IEEETran (often packaged as ``texlive-publishers``, or download from - [CTAN](http://www.ctan.org/tex-archive/macros/latex/contrib/IEEEtran/)) LaTeX - class - - AMSmath LaTeX classes (included in most LaTeX distributions) - - alphaurl (often packaged as ``texlive-bibtex-extra``, or download from - [CTAN](https://www.ctan.org/pkg/urlbst)) urlbst BibTeX style +- MyST Markdown (`mystmd`) and NodeJS (>18) +- GitHub actions for the build process -### Debian-like distributions: +## Build Process -``` -sudo apt-get install python-docutils texlive-latex-base texlive-publishers \ - texlive-latex-extra texlive-fonts-recommended \ - texlive-bibtex-extra -``` - -Note you will still need to install `docutils` with `pip` even on a Debian system. - -### Fedora - -On Fedora, the package names are slightly different: - -``` -su -c `dnf install python-docutils texlive-collection-basic texlive-collection-fontsrecommended texlive-collection-latex texlive-collection-latexrecommended texlive-collection-latexextra texlive-collection-publishers texlive-collection-bibtexextra` -``` - -## Build Server +The build process is completed through GitHub actions on every commit. +A comment is posted after the build process completes with a list of checks +and a link to the built output on Curvenote. -There will be a server online building open pull requests at http://procbuild.scipy.org. +**Authors**: you should check to ensure that your local builds match the papers +built online. Please create an issue if they do not match. -Authors: you should check to ensure that your local builds match the papers -built on this site. Please create an issue if they do not match. - -Reviewers: You should be able to pull a built PDF for review from there. +**Reviewers**: You should be able to see the built article from the GitHub comment, and review from the preview link. ## For organisers @@ -445,17 +427,19 @@ To information about how to manage the whole proceedings, please see - Apr 19: Authors invited to submit full papers - May 31–Aug 8: Open Review Period - - The [build server](#build-server) should be maintained throughout the Open Review Period. + - The [build process](#build-process) is supported by Curvenote (an SciPy sponsor) and it is maintained throughout the Open Review Period. - Aug 16: Time Window for Publishing Conference Ready Proceedings ### Instructions for Editors As reviewers review papers, editors should apply **labels** to the PR to flag the -current state of the review process. - - The **labels** in question are: - - **needs-more-review** if the paper needs further review, - - **pending-comment** if the paper is waiting on an authors' response, or - - **unready** if the paper is not ready for the proceedings. +current state of the review process. All paper PRs must have the `paper` label before the GitHub action will be triggered. Additionally, as editors and reviewers are assigned, the editors should add the reviewers GitHub handles to the PR summary comment. + +Other **labels** that should be used are: + +- **needs-more-review** if the paper needs further review, +- **pending-comment** if the paper is waiting on an authors' response, or +- **unready** if the paper is not ready for the proceedings. Editors should come to a final 'ready', 'unready' decision before the **Final Editorial Decisions for Proceedings Contents** deadline. @@ -467,7 +451,7 @@ Editors should come to a final 'ready', 'unready' decision before the **Final Ed - May 31–Aug 9: Open Review Period - May 31: Reviewers Assigned - Jun 21: Initial Complete Review - - Editors should verify that reviews have been completed + - Editors should verify that reviews have been completed - Aug 9: Final Editorial Decisions for Proceedings Contents Deadline ## Instructions for Slides @@ -478,31 +462,33 @@ Editors should come to a final 'ready', 'unready' decision before the **Final Ed 2. Update your local copy of the `scipy_proceedings` repo. 3. [Create a new branch](#creating-a-new-branch) for your paper based off the latest `2024` branch. 4. Inside the `presentations` folder, there are directories for: - 1. 3-minute lightning talk slide decks (lightning) - 2. Posters presented at the poster session (posters) - 3. 30-minute talk slide decks (slides) - 4. SciPy tools plenary slide decks (tools) + 1. 3-minute lightning talk slide decks (lightning) + 2. Posters presented at the poster session (posters) + 3. 30-minute talk slide decks (slides) + 4. SciPy tools plenary slide decks (tools) 5. Choose the appropriate folder, and make a new directory inside it (it needs a unique name) 6. Copy your slide deck or poster into the directory, and add a file called `info.json` with the following fields needed for uploading to Zenodo (using an empty string for author orcid or -affiliation if these cannot be provided): + affiliation if these cannot be provided): + ```json { - "title": "The title of your presentation", - "authors": [ - { - "name": "The first author or presenter", - "affiliation": "first author's affiliation", - "orcid": "0000-0000-0000-0000" - }, - { - "name": "The second author or presenter", - "affiliation": "second author's affiliation", - "orcid": "0000-0000-0000-0001" - } - ], - "description": "1-4 sentences explaining what your presentation is about" + "title": "The title of your presentation", + "authors": [ + { + "name": "The first author or presenter", + "affiliation": "first author's affiliation", + "orcid": "0000-0000-0000-0000" + }, + { + "name": "The second author or presenter", + "affiliation": "second author's affiliation", + "orcid": "0000-0000-0000-0001" + } + ], + "description": "1-4 sentences explaining what your presentation is about" } ``` + 7. [Create a PR](#create-a-paper-pr) You can see examples of submissions in the `example` folder in each presentation directory. diff --git a/make_paper.sh b/make_paper.sh deleted file mode 100755 index 6863b7df34..0000000000 --- a/make_paper.sh +++ /dev/null @@ -1,17 +0,0 @@ -#!/bin/bash - -DIR=$1 - -if [[ ! -d $DIR ]]; then - echo "Usage: make_paper.sh source_dir" - exit -1 -fi - -python publisher/build_paper.py $DIR -if [ "$?" -ne "0" ]; then - echo "Error building paper $DIR. Aborting." - exit 1 -fi - -#cd $OUTDIR -#$TEX2PDF > /dev/null && $TEX2PDF | (python $WD/publisher/page_count.py) diff --git a/publisher/README.md b/publisher/README.md index 450e902841..093b804a86 100644 --- a/publisher/README.md +++ b/publisher/README.md @@ -1,5 +1,7 @@ # For editors publishing the proceedings. +**Note**: This is changing in 2024 and aspects of this README are out of date. + ## Structure of the proceedings This section will give you an introduction to the various documents and resources that you will need to create in the course of managing the proceedings. @@ -44,11 +46,11 @@ The resulting html files will include: - `index.html` - a page for each article, named ``.html` - a `bib/`` directory, containing: - - a bibfile for each article, named `.bib` - - a bibfile for the complete proceedings, named `proc-scipy-.bib` + - a bibfile for each article, named `.bib` + - a bibfile for the complete proceedings, named `proc-scipy-.bib` - a `pdf/` directory, containing: - - a pdf for each article, named `.pdf` - - a pdf for the complete proceedings, named `proceedings.pdf` + - a pdf for each article, named `.pdf` + - a pdf for the complete proceedings, named `proceedings.pdf` ## Building the proceedings: Makefile @@ -86,6 +88,28 @@ NB: You will tend to use `html-zip` if you need to iterate on the portable copy of the website without needing to rebuild the entire proceedings. This is most useful after authors' PRs are no longer being updated. +## Requirements + +These requirements are for installing LaTeX, which should not be necessary for MyST based submissions. + +### Debian-like distributions: + +``` +sudo apt-get install python-docutils texlive-latex-base texlive-publishers \ + texlive-latex-extra texlive-fonts-recommended \ + texlive-bibtex-extra +``` + +Note you will still need to install `docutils` with `pip` even on a Debian system. + +### Fedora + +On Fedora, the package names are slightly different: + +``` +su -c `dnf install python-docutils texlive-collection-basic texlive-collection-fontsrecommended texlive-collection-latex texlive-collection-latexrecommended texlive-collection-latexextra texlive-collection-publishers texlive-collection-bibtexextra` +``` + ## Build styles There are three different modes for publishing the proceedings, you will need to @@ -106,18 +130,18 @@ can be served on the official SciPy organisation website. be used to publish the final version of the proceedings. Using "ready" is responsible for triggering the creation of DOIs and XML submission files. - ## DOI metadata +## DOI metadata As of 2015, each SciPy conference proceedings and the individual papers in one proceedings are assigned DOIs. As of 2018, the conference itself has a DOI, such that the linking structure now looks the following: - ISSN + Series DOI (10.25080/issn.2575-9752) - - Conference DOI for SciPy 2018 - - Conference DOI for SciPy 2017 - - Paper DOI for Poore 2017 - - Paper DOI for Niederhut 2017 - - etc. + - Conference DOI for SciPy 2018 + - Conference DOI for SciPy 2017 + - Paper DOI for Poore 2017 + - Paper DOI for Niederhut 2017 + - etc. The organization that administers ISSN requests that [the series-level DOI be constructed following these guidelines] @@ -134,6 +158,7 @@ This ends up looking like `10.25080/shinma-7f4c6e7-002`. When displaying DOIs, crossref.org asks that we use this format - [https://doi.org/10.25080/shinma-7f4c6e7-002] (https://doi.org/10.25080/shinma-7f4c6e7-002) + - which resolves the proceedings page where the paper is hosted. Submitting DOIs and associated metadata about each paper to crossref.org diff --git a/publisher/getting_ready_for_new_year.md b/publisher/getting_ready_for_new_year.md index 6513d091ee..618c65a5cc 100644 --- a/publisher/getting_ready_for_new_year.md +++ b/publisher/getting_ready_for_new_year.md @@ -1,35 +1,35 @@ # Getting ready for the new year's proceedings -We're going to assume that you are working in year *x* to set up the proceedings -system for SciPy *x*. +We're going to assume that you are working in year _x_ to set up the proceedings +system for SciPy _x_. This workflow requires a few steps. We will list those steps here, but if you -don't know what some of the words mean, we highly recommend that you read +don't know what some of the words mean, we highly recommend that you read [the problem section](#What-problem-are-we-solving). # Workflow All development work should have been occurring on the `dev` branch of the repo. -1. Merge `dev` into `master` -1. Create new branch for year `x` based off of the new `master` +1. Merge `dev` into `main` +1. Create new branch for year `x` based off of the new `main` 1. Update the default branch - ![Update default branch](./images/update_default_branch.png) 1. (potential step) If you have a new server location, you need to update the webhook 1. Update the docs to reflect all of the above changes - that includes: - - `scipy_proceedings/README.md` - - `scipy_proceedings/publisher/README.md` - - `scipy_proceedings/publisher/getting_ready_for_new_year.md` + - `scipy_proceedings/README.md` + - `scipy_proceedings/publisher/README.md` + - `scipy_proceedings/publisher/getting_ready_for_new_year.md` -## What problem are we solving? +## What problem are we solving? For the purposes of this explanation, we're going to describe the workflow in -terms of what needs to be done in the repo in the year `x = 2018`. +terms of what needs to be done in the repo in the year `x = 2018`. We organise the repo around git branches, specifically we're going to be thinking about 4 branches: -- `master`: the master branch, reflecting the canonical source of the proceedings system +- `main`: the main branch, reflecting the canonical source of the proceedings system - `dev`: the development branch, reflecting the up-to-date source of the proceedings system - `2017`: the previous year's proceedings' branch - `2018`: this year's proceedings' branch (this branch does not yet exist) @@ -37,41 +37,41 @@ We organise the repo around git branches, specifically we're going to be thinkin Most of the decisions we need to make revolve around what we want to do with each of these branches. -### What goes into `master`? +### What goes into `main`? -In `2017` we have a lot of things that differ from `master`. On the one hand, +In `2017` we have a lot of things that differ from `main`. On the one hand, there are all the great changes that were made by the previous year's proceedings committee. We're going to definitely want to have those in our -`master` branch. However, `2017` also has all of the papers that were submitted +`main` branch. However, `2017` also has all of the papers that were submitted by the authors of the 2017 proceedings. -**We never want to have any real papers in master, ever**. `master` is supposed +**We never want to have any real papers in main, ever**. `main` is supposed to only ever reflect the build system itself. That means the only papers that -should ever be in `master` should be the demo papers. +should ever be in `main` should be the demo papers. -We want to keep `master` and its history as small as possible. It is intended to +We want to keep `main` and its history as small as possible. It is intended to transcend any particular year, and should not be tied to any of the history of -the proceedings system. Additionally, this keeps `master` as small as possible. +the proceedings system. Additionally, this keeps `main` as small as possible. -So, we only want to put the changes to the build system in master. But people +So, we only want to put the changes to the build system in main. But people have to submit their proceedings to `2017` in 2017, and `2018` in 2018. How can -we get the improvements to the system without getting the papers? +we get the improvements to the system without getting the papers? ### `dev` is where build changes go -The solution to the previous section problems is the `dev` branch. +The solution to the previous section problems is the `dev` branch. `dev` specifically exists to house the improvements to the system, without any -of the papers. +of the papers. That means during the 2018 proceedings any work that is being done to improve the system should be in PRs made against `dev`, not `2018`. -### Base the new year's branch (e.g., `2018`) off of `master` +### Base the new year's branch (e.g., `2018`) off of `main` -After merging `dev` into `master`, can branch `2018` off of `master`. +After merging `dev` into `main`, can branch `2018` off of `main`. -### Merge `dev` into `2018` on an on-going basis. +### Merge `dev` into `2018` on an on-going basis. But as you are developing the system, you will be making changes to address specific problems that come up for authors. If we aren't putting any changes in @@ -92,4 +92,3 @@ TODO: Figure out workflow to move previous year's branch into its own repo. Once we write up the workflow, this should be added to the todo list under [](#Workflow). - diff --git a/requirements.txt b/publisher/requirements.txt similarity index 100% rename from requirements.txt rename to publisher/requirements.txt diff --git a/pull_request_template.md b/pull_request_template.md index b8223ace02..4445c945b7 100644 --- a/pull_request_template.md +++ b/pull_request_template.md @@ -1,11 +1,9 @@ If you are creating this PR in order to submit a draft of your paper, -see http://procbuild.scipy.org/ for logs generated by the build -process. +please tag your PR with `paper` and a GitHub Action will be run to check and build your paper. -See the [project readme](https://github.com/scipy-conference/scipy_proceedings#build-your-paper) +See the [project readme](https://github.com/scipy-conference/scipy_proceedings#preview-your-paper) for more information. +_Editor_: -*Editor*: - -*Reviewers*: +_Reviewers_: