info.arxiv.org pages

Help, about, policy and other pages for arXiv.

Overview

This is where to make edits to the about, help, labs, new and other pages at info.arxiv.org. These are written in markdown and turned into HTML pages with mkdocs-material.

How to do a Quick Edit on github

To make a quick edit, use this is a 4 step process:

1. Make your edit and commit to a new branch.

2. Make a PR from your branch to develop, get that reviewed.

3. Merge the PR to develop.

4. Merge changes on develop to master.
   
   

1. Make your edit on github

• To edit a page first go to the info.arxiv.org page you want to edit.
  Example: https://info.arxiv.org/help/gzip.html

• Click on the pencil icon to edit the page. That will take you to the corresponding page in github.

• On the page you want to edit in github, click the pencil to edit the page contents right in github.

• After you have made changes, click preview to see how it will look when completed.
  Please note: Github uses "Github flavored markdown" which is different from the markdown we use to create our documentation. There may be small variations in how the markdown appears due to these differences.

• Review your work in preview mode. To return to editing, click on "edit" in the header.

• Once you are happy with your changes you can save by clicking on the "Commit changes" button in the upper right hand corner. Commit is the term github and git use for saving.

• Add a brief note in the "Commit message" area summarizing your edit. You may add longer note in the "Extended description" area if you have more to say about your changes.

• Make sure you have your email associated with your commits.

• Note that a "new branch for this request and start a pull request" will be selected.

• Name your branch after your JIRA ticket (if applicable) or after your github username and brief description.
  Examples:
  arxivce-1503-update-arxiv-docs-readme
alisonhofer-update-arxiv-docs-readme

If you have more changes to make at this time you may make and commit them all to the branch you created. The additional changes you commit will be grouped together when you make your pull request in the next step.

2. Make a Pull Request from your branch to develop

Once you have completed all of your changes, you need to have your changes reviewed. This is done by "creating a PR." PR stands for pull request.

• At the top of your page you will notice a yellow box that will have the name of your commit and a button to the right of it that says "Compare & pull request".

• Click on Compare & pull request

In the event that you have made a commit and were unable to complete or create your pull request at the time, you will not have the same yellow box interface if you return to the page the next day.

You will have to make a pull request by clicking on the "Pull requests" link in the header of the github
Next, click the button to the right that says "New pull request"

• Compare your changes by clicking on the "compare:develop" dropdown and type in your branch name and then select your branch.
• This will compare your branch to the develop branch.

• Click on the "Files Changed" tab to view a comparison of the develop branch you are planning to merge into master.

• Click "Create pull request"
• Add a title for your pull request and a description if the title is not self explanatory.
• To the right, click on the gear icon to the right of "Reviewers".
• A dropdown will appear and request people to review your PR.
• If you are unsure who to ask to review your changes, check with your manager.

• After selecting reviewers, click the blue "Create pull request" button.

• Reviewers will receive an email from Github with a link to the PR to review.
• Additionally, you can slack your reviewers with a link to your PR to give them a heads up.

3. Merge the PR to develop

• Once your PR has been reviewed and approved you will receive an email notification with a link to your PR.
• Now you can merge your PR to develop.
• Open your PR and scroll down and click on "Merge pull request".

• You will be prompted to confirm you decision, click "Confirm merge".

  

• Please note: The above step will only put your changes on develop and they will not be viewable on the live site: info.arxiv.org. At this point you have only saved the edit(s) in github.

• You can review your changes on the develop site at info.dev.arxiv.org.

4. Make a Pull Request from develop to master

Please note: Once you have merged your changes to develop, it is important to deploy them as soon as possible. Lingering commits on on the develop branch can cause unintentional problems when they are deployed with other code. If you notice commits other than your own in the PR you make, please be sure to check in with the owners of those commits to ensure they are ready to go live.

• Now that your PR has been merged to develop, you need to deploy these changes to master.
• To make a new PR click the "Pull requests" link in the header of the github page.
• On the right hand side, click the blue button that says "New pull request"

• Compare your changes by clicking on the "base:develop" dropdown on the left and type in "master" and then select it.
• This will compare your branch to the develop branch.

• Click on the "Files Changed" tab to view a comparison of the develop branch you are planning to merge into master.

• Click "Create pull request"

• Add a title for your pull request and a description if the title is not self explanatory.

• To the right, click on the gear icon to the right of "Reviewers"

• A dropdown will appear and you can request people to review your PR.

• After selecting reviewers, click the blue "Create pull request" button.

• Ping your reviewers in slack with a link to your PR and ask them to review it.

• Once your PR has been reviewed and approved you can merge your PR to master.

• Open your PR and scroll down and click on "Merge pull request".

• You will be prompted to confirm you decision, click "Confirm merge".

• You will see your changes on production about 15 minutes after you have confirmed your merge.

Authoring Markdown

See AUTHORING.md

Building on your local machine

Instead of using github to edit you can check all the files for arxiv-docs to your laptop to edit and preview.

git clone [email protected]:arXiv/arxiv-docs.git
cd arxiv-docs
python --version
# 3.8.12
python -m venv docs-venv
source docs-venv/bin/activate
pip install -r requirements.txt
mkdocs serve
google-chrome https://localhost:8000/index.html

Then you will have the site served locally with hot reloading on edits. In your browser, go to http://localhost:8000/index.html

Deployment to info.arxiv.org

Commits or merges to arxiv-docs master branch will deploy the site.

The cloud build YAML files combined with CloudBuild triggers in arxiv-production comprise the deployment pipeline for arxiv-docs.

Previews of PRs

PRs that will merge to the branch develop on the github repo arxiv-docs will deploy previews at https://storage.googleapis.com/arxiv-docs-prs/YOUR_BRANCH_NAME/about/index.html

Note that the home page specifically does not exist, but any other page can be accessed with its URL path. This preview can been seen by the public, everything in the github arxiv-docs repo can also be seen by the public.

Direct commits to the develop branch will not generate a preview.

Historical site content

See https://github.com/arXiv/arxiv-docs/releases for branches prior to 2023 when content was shifted to the source/ directory.