Skip to content

Commit

Permalink
chore: Run make linkcheck
Browse files Browse the repository at this point in the history
  • Loading branch information
jpmckinney committed Jun 29, 2023
1 parent f733144 commit c3f0e9b
Show file tree
Hide file tree
Showing 23 changed files with 72 additions and 64 deletions.
24 changes: 16 additions & 8 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,25 +54,33 @@

linkcheck_anchors_ignore = [
# GitHub readme headings.
r'^(?:change-github-repository-configuration|commit-message-header|tests|unsafe-transforms)$',
r'^(?:change-github-repository-configuration|commit-message-header|github|inputs|node-sass'
r'|requesting-message-acknowledgements-from-another-thread|tests|unsafe-transforms|L22-L24)$',
]
linkcheck_ignore = [
# Localhost instructions.
r'^http://localhost:8000',
r'^http://127.0.0.1',
# Returns 404 to linkcheck.
r'^https://crates.io',
# Redirects to login pages.
r'^https://(?:crm\.open-contracting\.org|redash\.open-contracting\.org)',
r'^https://(?:app\.usefathom\.com/#|console\.aws\.amazon\.com|readthedocs\.org/dashboard|sentry\.io/settings)/.+',
r'^https://(?:admin\.google\.com|myaccount\.google\.com)/.+',
r'^https://(?:docs\.google\.com/(?:document|spreadsheets)/d|drive\.google\.com/drive/folders)/.+',
r'^https://console\.cloud\.google\.com/.+\?organizationId=.+',
r'^https://groups\.google\.com/a/open-contracting\.org/g/standard-discuss/members\?.+',
r'^https://(?:app\.usefathom\.com/#|console\.aws\.amazon\.com|readthedocs\.org/dashboard|sentry\.io/settings)/.+',
r'^https://github\.com/(?:organizations/open-contracting/settings|orgs/open-contracting/teams)/.+',
r'^https://www\.transifex\.com/.+/collaborators/$',
r'^https://github\.com/(?:organizations/open-contracting/settings/.+|orgs/open-contracting/teams|issues/assigned$)',
r'^https://airtable\.com/.+/workspace/billing$',
r'^https://coveralls\.io/repos/new$',
r'^https://pypi\.org/manage/account/#api-tokens$',
r'^https://readthedocs\.org/dashboard/$',
r'^https://sentry\.io',
r'^https://app\.transifex\.com/.+/(collaborators|settings)/$',
r'^https://cards-dev\.twitter\.com/validator$',
# Redirects to specific versions.
r'https://docs\.pytest\.org/$',
r'https://click\.palletsprojects\.com/$',
r'https://flask\.palletsprojects\.com/$',
r'https://jinja\.palletsprojects\.com/$',
r'^https://docs\.pytest\.org/$',
r'^https://click\.palletsprojects\.com/$',
r'^https://flask\.palletsprojects\.com/$',
r'^https://jinja\.palletsprojects\.com/$',
]
4 changes: 2 additions & 2 deletions docs/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This website documents OCP's policies around software development. This page des
Policy proposal
---------------

The current process is extremely lightweight: create a GitHub issue, and discuss with the Head of Data Products and Services. A structured process might look like `Datamade: Making changes to the stack <https://github.com/datamade/how-to/blob/master/CONTRIBUTING.md>`__.
The current process is extremely lightweight: create a GitHub issue, and discuss with the Head of Data Products and Services. A structured process might look like `Datamade: Making changes to the stack <https://github.com/datamade/how-to/blob/main/CONTRIBUTING.md>`__.

Policy implementation
---------------------
Expand All @@ -18,4 +18,4 @@ However, some policies might be harder or longer to implement across all project
Reference
---------

- `Datamade: Making changes to the stack <https://github.com/datamade/how-to/blob/master/CONTRIBUTING.md>`__. See research for `Heroku <https://github.com/datamade/how-to/blob/master/deployment/heroku/research/recommendation-of-adoption.md>`__, `Gatsby <https://github.com/datamade/how-to/tree/master/gatsby/research>`__ and `Wagtail <https://github.com/datamade/how-to/tree/master/django/wagtail/research>`__.
- `Datamade: Making changes to the stack <https://github.com/datamade/how-to/blob/main/CONTRIBUTING.md>`__. See research for `Heroku <https://github.com/datamade/how-to/blob/main/deployment/heroku/research/recommendation-of-adoption.md>`__, `Gatsby <https://github.com/datamade/how-to/tree/main/javascript/gatsby/research>`__ and `Wagtail <https://github.com/datamade/how-to/tree/main/django/wagtail/research>`__.
2 changes: 1 addition & 1 deletion docs/docker/build.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ If you need to build multiple images, then for each image:

.. note::

The `docker/build-push-action <https://github.com/docker/build-push-action>`__ step uses `BuildKit <https://docs.docker.com/engine/reference/builder/#buildkit>`__ by default.
The `docker/build-push-action <https://github.com/docker/build-push-action>`__ step uses `BuildKit <https://docs.docker.com/build/buildkit/>`__ by default.

..
The following would simplify the workflow somewhat. However, it would not work when building multiple images, producing an inconsistent approach across repositories.
Expand Down
2 changes: 1 addition & 1 deletion docs/docker/django.rst
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Reference: `Signal Handling <https://docs.gunicorn.org/en/stable/signals.html>`_
Other options
~~~~~~~~~~~~~

``--bind 0.0.0.0:8000`` uses Docker's `default bind address for containers <https://docs.docker.com/network/iptables/#setting-the-default-bind-address-for-containers>`__ and Gunicorn's `default port <https://docs.gunicorn.org/en/stable/settings.html#bind>`__.
``--bind 0.0.0.0:8000`` uses Docker's `default bind address for containers <https://docs.docker.com/network/packet-filtering-firewalls/#setting-the-default-bind-address-for-containers>`__ and Gunicorn's `default port <https://docs.gunicorn.org/en/stable/settings.html#bind>`__.

``--worker-tmp-dir /dev/shm`` avoids a `potential issue <https://docs.gunicorn.org/en/stable/faq.html#how-do-i-avoid-gunicorn-excessively-blocking-in-os-fchmod>`__.

Expand Down
2 changes: 1 addition & 1 deletion docs/git/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Most commits are made in pull requests, such that it's easy to find the discussi

Reference:

- `Angular Commit Message Format <https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit-message-header>`__
- `Angular Commit Message Format <https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit-message-header>`__
- `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`__
- `Write joyous git commit messages <https://joshuatauberer.medium.com/write-joyous-git-commit-messages-2f98891114c4>`__

Expand Down
4 changes: 2 additions & 2 deletions docs/github/developers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@ All issues should be closed with a brief rationale. This makes it easy to unders
Pull requests
-------------

**DO NOT** force-push changes to a pull request in response to a code review. Force-pushing makes it impossible to use GitHub's *View changes* feature. If you want a single commit, select `Squash and merge <https://docs.github.com/en/github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges>`__ from the *Merge pull request* dropdown.
**DO NOT** force-push changes to a pull request in response to a code review. Force-pushing makes it impossible to use GitHub's *View changes* feature. If you want a single commit, select `Squash and merge <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges>`__ from the *Merge pull request* dropdown.

Projects
--------

The ``open-contracting`` `organization <https://github.com/orgs/open-contracting/projects>`__ uses `GitHub Projects <https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards>`__ to organize work in a `Kanban <https://en.wikipedia.org/wiki/Kanban>`__ system.
The ``open-contracting`` `organization <https://github.com/orgs/open-contracting/projects?query=is%3Aopen>`__ uses `GitHub Projects <https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards>`__ to organize work in a `Kanban <https://en.wikipedia.org/wiki/Kanban>`__ system.

People expect to have visibility of all of a repository’s issues within the *Issues* tab; therefore, a card that is not attached to an issue should never be added to a project.

Expand Down
12 changes: 6 additions & 6 deletions docs/github/maintainers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -57,15 +57,15 @@ Onboard consultants or Start a project
#. Add any projects to :ref:`ReadTheDocs<readthedocs>` as appropriate
#. Use the :doc:`Django Cookiecutter template<../python/django>`, if relevant

If consultants need to make changes that require Admin privileges, instead, ask the consultants for instructions to make the changes yourself, or create a `custom role <https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization>`__.
If consultants need to make changes that require Admin privileges, instead, ask the consultants for instructions to make the changes yourself, or create a `custom role <https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization>`__.

Do not use `outside collaborators <https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization>`__. Individual consultants can be collected into appropriate teams, like the `Standard <https://github.com/orgs/open-contracting/teams/standard>`__ team.
Do not use `outside collaborators <https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization>`__. Individual consultants can be collected into appropriate teams, like the `Standard <https://github.com/orgs/open-contracting/teams/standard>`__ team.

Per the `Software terms of reference (TOR) template <https://docs.google.com/document/d/13-_eFQrelLdj92MWTiqzAfO62in7Xxrv3DTcmRqvNjE/edit>`__, consultants should not have access to the production server. As such, do not add any members to the `Servers <https://github.com/orgs/open-contracting/teams/servers>`__ team.

.. warning::

**NEVER** assign the Owner role to non-OCP staff. The Owner role has access to a private repository with multi-factor authentication backup codes. `Transferring a repository <https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/transferring-a-repository>`__ does not require the Owner role.
**NEVER** assign the Owner role to non-OCP staff. The Owner role has access to a private repository with multi-factor authentication backup codes. `Transferring a repository <https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository>`__ does not require the Owner role.

.. tip::

Expand Down Expand Up @@ -95,7 +95,7 @@ Protect branches

Use the `fix:protect_branches <https://github.com/open-contracting/standard-maintenance-scripts#change-github-repository-configuration>`__ task to protect branches.

We don’t generally enable the following behaviors on `protected branches <https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches>`__ for the provided reasons:
We don’t generally enable the following behaviors on `protected branches <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches>`__ for the provided reasons:

- **Require branches to be up to date before merging**: While this may avoid introducing errors, it slows development in an environment in which there are many simultaneous pull requests, because each would require an extra step before merging. If the automated tests fail after merging, the error can be corrected, or the changes can be reverted.
- **Require pull request reviews before merging**: While this is a best practice, it slows development as the team is not sufficiently large to staff it. It is okay, for example, for an author to self-merge a simple change. Authors may, of course, request reviews for significant changes.
Expand All @@ -118,9 +118,9 @@ Repositories that are no longer supported should be archived.
- Merged changes to the core standard, expressed as extension repositories (``ocds_upgrade_###``)
- Exploratory repositories from pre-1.0 and pre-2015

#. Scan the repository’s open issues, milestones, pull requests and non-default branches in case any can be quickly closed, merged or deleted. Counter `GitHub’s recommendation <https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/about-archiving-repositories>`__, open issues and pull requests indicate the development status of a repository, and should be left open.
#. Scan the repository’s open issues, milestones, pull requests and non-default branches in case any can be quickly closed, merged or deleted. Counter `GitHub’s recommendation <https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories>`__, open issues and pull requests indicate the development status of a repository, and should be left open.
#. Change the repository’s description to describe the reason for archival. If the repository has been superseded, change it to “Superseded by [owner]/[repository]” and change the URL to the new repository’s URL.
#. Run the `fix:archive_repos REPOS=repo1,repo2 <https://github.com/open-contracting/standard-maintenance-scripts#change-github-repository-configuration>`__ task on the repository.
#. Move the archive to the ``open-contracting-archive`` organization.
#. `Archive <https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/about-archiving-repositories>`__ the repository through its settings.
#. `Archive <https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories>`__ the repository through its settings.
#. Run the `local:badges <https://github.com/open-contracting/standard-maintenance-scripts#change-github-repository-configuration>`__ task.
6 changes: 3 additions & 3 deletions docs/htmlcss/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Frameworks
Most projects use `Bootstrap <https://getbootstrap.com>`__. Designers are free to use other frameworks like:

- `Tailwind <https://tailwindcss.com>`__, a `utility classes <https://adamwathan.me/css-utility-classes-and-separation-of-concerns/>`__ framework
- `Vuetify <https://vuetifyjs.com>`__, a `Material Design <https://material.io/design>`__ framework
- `Vuetify <https://vuetifyjs.com>`__, a `Material Design <https://m3.material.io>`__ framework

When using Bootstrap, `customize <https://getbootstrap.com/docs/5.2/customize/sass/>`__ it and `@import only the components you need <https://getbootstrap.com/docs/5.2/customize/optimize/>`__.

Expand Down Expand Up @@ -82,12 +82,12 @@ Code style

Style CSS code using `Prettier <https://prettier.io>`__ with 2-space indentation. In terms of naming conventions, options include:

- `Block Element Modifier (BEM) <http://getbem.com>`__
- `Block Element Modifier (BEM) <https://getbem.com>`__

Development
~~~~~~~~~~~

- `Tachyons X-ray <http://tachyons.io/xray/>`__ to align objects to a grid
- `Tachyons X-ray <https://tachyons.io/xray/>`__ to align objects to a grid

Reference
---------
Expand Down
8 changes: 4 additions & 4 deletions docs/javascript/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -40,26 +40,26 @@ Frontend code is written for ECMAScript 6 (ES6) (`see the status of feature supp
]
}
To transform newer code to ECMAScript 6, use `Babel <https://babeljs.io>`__ with the `defaults <https://babeljs.io/docs/en/babel-preset-env#no-targets>`__ query from `browserlist <https://github.com/browserslist/browserslist>`__.
To transform newer code to ECMAScript 6, use `Babel <https://babeljs.io>`__ with the `defaults <https://babeljs.io/docs/options#no-targets>`__ query from `browserlist <https://github.com/browserslist/browserslist>`__.

Node
~~~~

Applications are written for the latest LTS version of Node. Packages are written for non-end-of-life versions (`see the status of Node versions <https://endoflife.date/nodejs>`__).

To upgrade Node, change the ``node-version`` key in GitHub Actions workflows and the ``node`` (or ``nikolaik/python-nodejs``) image in Dockerfiles. Check the relevant `changelog <https://github.com/nodejs/node/blob/master/CHANGELOG.md>`__ for breaking changes.
To upgrade Node, change the ``node-version`` key in GitHub Actions workflows and the ``node`` (or ``nikolaik/python-nodejs``) image in Dockerfiles. Check the relevant `changelog <https://github.com/nodejs/node/blob/main/CHANGELOG.md>`__ for breaking changes.

.. _javascript-preferences:

Preferences
-----------

Plain JavaScript is preferred to using jQuery, unless functionality depends on jQuery plugins. To replace jQuery in a project, refer to `You Might Not Need jQuery <http://youmightnotneedjquery.com>`__. Similarly, use the `Fetch <https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API>`__ API instead of the `Axios <https://axios-http.com>`__ package, etc.
Plain JavaScript is preferred to using jQuery, unless functionality depends on jQuery plugins. To replace jQuery in a project, refer to `You Might Not Need jQuery <https://youmightnotneedjquery.com>`__. Similarly, use the `Fetch <https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API>`__ API instead of the `Axios <https://axios-http.com>`__ package, etc.

Package manager
`npm <https://docs.npmjs.com>`__, the default package manager of Node.js. Do not use `yarn <https://yarnpkg.com>`__.
User interface
`Vue <https://vuejs.org>`__ is preferred to `React <https://reactjs.org>`__. That said, do not use frameworks for simple interfaces.
`Vue <https://vuejs.org>`__ is preferred to `React <https://react.dev>`__. That said, do not use frameworks for simple interfaces.
Asset management
`webpack <https://webpack.js.org>`__, unless a framework provides its own, like `Vue <https://cli.vuejs.org>`__.
Sass
Expand Down

0 comments on commit c3f0e9b

Please sign in to comment.