There are multiple pages of documentation that provide conceptual and reference information about the concept of a "session" and how it is handled/measured, both generally and in specific WMF data sources. These documentation pages should be combined or deduplicated, and a single source of truth page should be linked to from the related Glossary entries in DataHub. Currently, https://wikitech.wikimedia.org/wiki/Analytics/Sessions is linked to from the DataHub glossary entries, but the wiki page hasn't had a meaningful content edit since 2023, and it isn't easily discoverable from related documentation in the Data_Lake/Traffic subpages nor from the related documentation on Meta-Wiki.
- https://wikitech.wikimedia.org/wiki/Analytics/Sessions
- https://wikitech.wikimedia.org/wiki/Analytics/Data_Lake/Traffic/SessionLength
- https://wikitech.wikimedia.org/wiki/Analytics/Data_Lake/Traffic/mobile_apps_session_metrics
- https://meta.wikimedia.org/wiki/Research:Activity_session
- https://meta.wikimedia.org/wiki/Research:Estimating_session_duration
- DataHub glossary entry: [[ https://datahub.wikimedia.org/glossaryTerm/urn:li:glossaryTerm:0f6b8770-8db9-4eb5-b205-4225daf5bb1b/Documentation?is_lineage_mode=false | Activity Session ]]
- DataHub glossary entry: [[ https://datahub.wikimedia.org/glossaryTerm/urn:li:glossaryTerm:1921bcda-850a-42b4-aa57-9c3cd093d069/Documentation?is_lineage_mode=false | Browser session ]]
###Background
Product teams across our organization have been implementing single page application (SPAs) tools and other pages outside of the MediaWiki domain. These pages are not influenced by skins, and their designs were freely tailored to their projects and users' needs. As a result, the interfaces of these solutions are not consistent with each other or the rest of Wikimedia core pages.
Some examples of these tools are:
- [[ https://en.wikipedia.org/wiki/Special:ContentTranslation#suggestions | Special:ContentTranslation ]] (Actually part of the MediaWiki domain, but overriding the default skins)
- [[ https://mismatch-finder.toolforge.org/ | Wikidata Mismatch Finder ]]
- [[ https://query.wikidata.org/querybuilder/?uselang=en | Wikidata Query Builder ]]
- [[ https://item-quality-evaluator.toolforge.org/ | Wikidata Item Quality evaluator ]]
###Problem
There's ambiguity regarding whether SPAs and other non-MediaWiki pages should conform, and to which degree, to Codex/Wikimedia design style guidelines involving layout and grid design, font styles, etc. The ambiguity increases in cases where the tools need to transition to utilizing Codex components and styles.
Without a clear direction, future design efforts may continue to face challenges in deciding whether and when to maintain consistency and alignment with Wikimedia standards.
###Solution
We should decide on the expected level of standardization of SPAs and document whether it is acceptable for them to maintain the current level of freedom or if, instead, these pages should adhere more closely to Codex and/or Wikimedia design style guidelines.
###Potential approaches
We should evaluate the advantages and disadvantages (implications for scalability, consistency and usability) of the following options:
1. The design of non-MediaWiki pages should adhere to Codex design guidelines: We should define the necessary design requirements (layout, font styles, etc.) that these tools should follow.
2. Non-MediaWiki pages should be aligned with the rest of Wikimedia core pages (e.g. emulate the default Vector 2022 skin).
3. Maintain the current level of freedom.
###Considerations
- We should evaluate which (other) key stakeholders should be involved in this decision.
###Aceptance criteria
[] We have defined and documented a unified approach to designing non-MediaWiki pages
As a method for early iteration, implement the information architecture designed in T363016 on the AQS doc site using placeholder or rough content.
- [ ] Implement information architecture on the site with placeholder content
- [ ] Collect feedback from the team
- [ ] Collect user feedback (lightweight process)
- [ ] Iterate on information architecture and [style guide](https://docs.google.com/spreadsheets/d/1QjrSNciiiCnjcrqOBbvXYBxFxRhJ4bZpp3OoWsVdMAE/edit#gid=785187642)
- [ ] Set up project repo
- [ ] Set up RapiDoc integration and component
- [ ] Add a note to the site homepage that the site is under construction
- [ ] Set up the build pipeline so the site can be published to doc.wikimedia.org during development for ease of collecting feedback, but don't add the link to the doc.wikimedia.org homepage for now
Create an information architecture for organizing the AQS user documentation on a dedicated static site
- [x] Create proposal (private Google Doc until tech writer review is complete)
- [ ] Tech writer review
Team review and user feedback will be done after implementing a prototype
Update the Editor Analytics API spec to conform to the style guide created in T361890
Spec: https://gerrit.wikimedia.org/r/plugins/gitiles/generated-data-platform/aqs/editor-analytics/+/refs/heads/main/docs/swagger.json
Update the Edit Analytics API spec to conform to the style guide created in T361890
Spec: https://gerrit.wikimedia.org/r/plugins/gitiles/generated-data-platform/aqs/edit-analytics/+/refs/heads/main/docs/swagger.json
Update the Page Analytics API spec to conform to the style guide created in T361890
Spec: https://gerrit.wikimedia.org/r/plugins/gitiles/generated-data-platform/aqs/page-analytics/+/refs/heads/main/docs/swagger.json
Update the Media Analytics API spec to conform to the style guide created in T361890
Spec: https://gerrit.wikimedia.org/r/plugins/gitiles/generated-data-platform/aqs/media-analytics/+/refs/heads/main/docs/swagger.json
Update the Geo Analytics API spec to conform to the style guide created in T361890
Spec: https://gerrit.wikimedia.org/r/plugins/gitiles/generated-data-platform/aqs/geo-analytics/+/refs/heads/main/docs/swagger.json
Update the Device Analytics API spec to conform to the style guide created in T361890
Spec: https://gerrit.wikimedia.org/r/plugins/gitiles/generated-data-platform/aqs/device-analytics/+/refs/heads/main/docs/swagger.json
Currently, the REST API framework is designed to manage a flat list of endpoint routes.
Versioning is applied per the conventioned established in T232485, but there is no mechanism to ensure copnsistency between related endpoints.
All core endpoints are currently exposed under the v1 version prefix, while each extension uses a separate prefix, typically followed by v0 marking the API as unstable.
This approach is problematic in the context of {T323786}. Since we only have a flat list of endpoints, we can only generate a single spec that cover all of them. But that spec will be different on each wiki, depending on what extensions are enabled, so it cannot be versioned in a way that would provide useful guarantees to clients. This prevents proper change management for API endpoints.
To provide stable specs with meaningful versioning, the REST API should support the notion of "modules" that group related endpoints together. Each module will produce a seperate spec with a meaningful version. The version in the spec will correspond to the version in the endpoint URL (though only the major version number will be used in the URL). Each extension would define a separate module (or multiple). The endpoints exposed by core can be grouped into modules as well, to decouple the evolution of unrelated groups of endpoints.
Each module would be defined by a speparate file declaring the routes supported by it. The format of these files could be made compatible with OpenAPI spec files.
Note that we may still offer a aggregated spec covering all endpoints for ease of exploration. That spec would however be considerd an unversioned snapshot, it would not provide any guarantees across wikis or over time.
In practice, this couple mean for example:
* The endpoints currently available under /v1/page/{title} and /v1/revision/{id} would move to /content.v1/page/{title} and /content.v1/revision/{id} respectively.
* We would generate an OpenAPI spec for all endpoints under /content.v1/, which would be using semantic versioning and provide guarantees across wikis and over time.
This ticket does not cover the introduction of any specific modules however. Just the ability to define modules. After that work is done, the next step will probably be making extensions define separate modules. We will probably also define a module for core content endpoints to supprt {T334238}.
**Feature summary** : I would like to (I assume) use the props param on wbsearchentities.
The documentation currently says: https://www.wikidata.org/w/api.php?action=help&modules=wbsearchentities
props:
Return these properties for each entity.
Values (separate with | or alternative): url
Default: url
but it doesn't explain what the URL should be.
The example at the bottom of the page passes the value as:
https://www.wikidata.org/w/api.php?action=wbsearchentities&search=alphabet&language=en&props=
which I assume is a mistake (why would you pass an empty value?)
**Use case(s)** : Using wbsearchentities would be good. Or at least understanding what it does.
**Benefits** :
This has confused multiple people. For example on telegram: https://t.me/c/1224298920/93369 and https://t.me/c/1224298920/100604 and myself
== Background
Currently, as of Codex v1.3.6, we have a misconception in our docs on icon usage within Links.
While the specifications already point out that there is only one specific icon put end of Link description
{F45964044}
“Link with icon” features {F45964323} as end icon and in normal size, which is against design agreements and common practice.
== Goal
Clarify Link with Icon usage with correct use cases.
See, for example, https://www.wikifunctions.org/view/en/Z15717: is Boolean
There are two implementations. The first is simple Python and tests take around 6000 ms. The second is a composition and tests take around 4000 ms. Similar differences (probably more significant) can be seen using Try this implementation. And yet, this composition is simply defined as: If(is Boolean(Argument reference("Z15717K1")), true, false), so it’s exactly the same code that provides the evaluation. It just requires less time to orchestrate. I’ve no idea why this should be so, but the explanation might help improve orchestration more generally.
Apologies if I’m missing the blindingly obvious!
Are you a Toolforge and/or Cloud VPS user? Is there documentation that you'd like to see created, updated or improved? Are you missing a tutorial for your favorite language or framework? If so, add a comment to this task with a short description of your wish and links to any existing docs.
If you would like to help creating/editing docs, add yourself as a subscriber to this task, together with a comment saying what you'd like to work on.
I will update this task with a list of docs to work on closer to the date.
We have a Swagger-UI interface for exploring REST APIs exposed by RESTbase: https://en.wikipedia.org/api/rest_v1/
We want to have the same ability for APIs exposed by MediaWiki core and extensions.
There is a lot of shared functionality between AQS 2.0 endpoints. For example, `project` and other shared parameters, timestamp formats, and the concepts of net and absolute. To ensure these shared elements are documented consistently and to make it easier to document new services, create a style guide that standardizes the way we document these elements.
### To do
- [x] Set up a [spreadsheet](https://docs.google.com/spreadsheets/d/1QjrSNciiiCnjcrqOBbvXYBxFxRhJ4bZpp3OoWsVdMAE/edit#gid=0) with all documentation fields
- [x] Discuss each field and decide on a standard (progress tracked in spreadsheet)
## Status
[x] Write draft
[x] Tech writer review
[x] Team review
## Context
The purpose of this task is to decide on a tool to display AQS OpenAPI specifications on a static documentation site powered by Vitepress.
OpenAPI is a formal standard for describing HTTP APIs. Originally known as Swagger Specification, it's a common way of providing machine-readable, testable descriptions of an API. Many tools in the OpenAPI ecosystem allow developers and users to design, analyze, explore and document APIs.
Including an OpenAPI specification tool on the documentation website has many benefits. It allows users to run code samples and directly query the API in the context of documentation. It also provides a standard, familiar way of exploring the API - its endpoint structure, parameters, and responses.
When combined with tutorials and reference materials, an OpenAPI specification tool provides a complete learning experience beneficial to API users of different proficiency levels.
### Approaches considered
Approach #1: Embed the tool and the specification as a page within a page. Allow users to navigate between paths using a dedicated tool sidebar (without changing the page).
This approach is relatively easy to configure but produces inconsistent user experience on the documentation site. It's difficult to work with the structure of the documentation with pages within pages.
Approach #2: Embed partial specifications. That is, allow for parts of the specification to be embedded separately within the existing documentation structure, without replacing that structure.
This produces a more consistent user experience but has a bit more involved configuration. Essentially, this means adding a specification component for every path or endpoint.
### Resulting tool requirements
- Can be embedded in documentation content. The tool shouldn't replace the entire documentation page, and it shouldn't force a documentation structure that matches the structure of the API.
- Can be customized to look like an integral part of the documentation page. This means it should have appropriate styling options, including the option to use the same typeface and colors as the rest of the documentation page. It shouldn't be perceived as a separate service or tool.
- Can be handled automatically as a dependency of the documentation site using well-understood tooling. This is to ensure the process of deployment is straightforward and easy to reason about.
- Can be used with a single, straightforward command. This is to ensure that the documentation for new endpoints is easy to produce and maintain.
- Allows readers to change parameters and issue requests to the API and see the response without leaving the documentation.
## Options considered
The two main options we considered were [[ https://github.com/rapi-doc/RapiDoc | RapiDoc ]] and [[ https://github.com/scalar/scalar | Scalar ]].
### RapiDoc
RapiDoc is a web component in two versions - regular and mini. The regular version behaves like a single page application, with search and navigation alongside spec content. As such, it's less interesting to us.
The mini version allows us to display information for a specific endpoint or a group of endpoints matching a specific path. This version is easier to embed in documentation content.
RapiDoc pros:
- Satisfies the requirements
- Familiar design
- Many configuration options
- The only tool of its kind with the mini version that perfectly matches our use case
- Doesn't issue any external calls when configured properly
RapiDoc cons:
- Few CSS customization options. While the colors can generally be changed, we can't modify the layout of the component to, for example, increase margins or padding where we think it might be necessary.
- Slightly dated design
- Effectively maintained by a single developer, and hasn't been updated in five months at the time of this writing. 17 pull requests in its repository are awaiting a response.
#### Screenshots
{F45842616}
{F45842619}
{F45842620}
{F45842617}
### Scalar
Scalar is an open-source (MIT-licensed) version of a commercial product (https://scalar.com/). It's a customizable specification viewer with a sophisticated API client interface.
Scalar pros:
- Satisfies the requirements
- Modern design that's relatively customizable using CSS
- Code samples in many programming languages using many common libraries
- Impressive interface for trying out the API
- Actively maintained as part of a commercial product
Scalar cons:
- Fewer customization options
- No dedicated mini version to focus only on specific API paths, though it's likely possible to achieve by customizing the design
- No option to disable calls to external services (Cloudflare and Google). These calls are made to load additional fonts (even if they're not in use) and syntax highlighter libraries (used in code samples). This could likely be fixed either via a PR or forking the repository.
- Needs additional configuration to work well with `vitepress build`.
#### Screenshots
{F45842863}
{F45842866}
{F45842865}
{F45842869}
### Other
The following options were considered but eliminated because they didn't satisfy the basic requirements.
#### OpenAPI Explorer
Fork of RapiDoc with some extra features, but fewer options that are actually useful to us. Specifically, it doesn't support the `mini` layout, which only displays selected paths. It also seemed more buggy than the other options, sometimes failing to load and requiring a page refresh.
#### vitepress-theme-openapi
Dedicated Vitepress theme for OpenAPI specifications. Provides limited options to interact with the API, and forces a specific structure and design that doesn't match our vision for the documentation.
## Proposal
Use RapiDoc mini as the main OpenAPI specification tool. Wrap it in a Vue component that can be used inside markdown files with minimal configuration.
In the meantime, explore the possibility of fixing or mitigating problems with Scalar and the possibility of replacing RapiDoc mini with Scalar in the near future without requiring changes in the documentation.
## Decision
Use RapiDoc mini as the OpenAPI specification tool on the documentation site. Investigate how to fix or mitigate problems with Scalar, and migrate to Scalar when these problems are solved.
## Consequences
# Set up a GitLab repository for the documentation site, with the correct dependencies and structure.
- Ensure the wrapper component around RapiDoc is straightforward to use, and can be embedded in documentation content.
- Ensure it's easy to make and test changes to Scalar in parallel, for example in a separate branch.
# Set up the build process for the new documentation site using GitLab CI and [[ https://gitlab.wikimedia.org/repos/releng/docpub | docpub ]].
# Investigate improvements to Scalar. Replace RapiDoc with Scalar inside the wrapper component if the improvements mitigate or solve its current problems.
# Document the site, its code, components, and the build process.
## Status
- [x] Write draft
- [x] Tech writer review
- [x] Team review
## Context
The documentation for AQS 1.0 exists in two places:
- pages on Wikitech with tutorials, guides, and links to the reference documentation (See this [list of links](https://wikitech.wikimedia.org/wiki/Data_Engineering/Systems/AQS#Hosted_API).)
- reference documentation in the form of OpenAPI specs served using Swagger UI through the [RESTBase API docs](https://wikimedia.org/api/rest_v1/#/)
There is no user-focused entry point for all AQS 1.0 API docs.
For the new AQS 2.0 services, we have the opportunity to reconsider where we store this documentation. This decision record describes two options we considered and makes a recommendation.
### Scope
This decision only covers user documentation for AQS (tutorials, guides, and reference docs). Maintainer docs (deployment guides, data processes, etc.) for AQS will remain on Wikitech as is standard practice for Wikimedia infrastructure documentation.
### Goals
- Users can easily discover and share AQS APIs through a single entry point
- Users can find information they need within the docs
- Contributors can easily maintain the docs
## Options considered
### 1. Wiki pages with standalone API specs (AQS 1.0 model)
In this approach, landing pages, tutorials, and guides are stored on wiki pages. These wiki pages link to the OpenAPI specs which are served separately through doc.wikimedia.org.
#### User experience
Users arrive at an on-wiki landing page where they can navigate to other wiki pages with more information about the API or use case they're interested in. They are then directed off the wiki to view the API spec on a different site.
#### Advantages
- Storing docs on wiki makes editing easy and fast.
- Search is integrated with wiki search. For example, searching for "monthly pageview count" on Wikitech brings you to the Pageviews API docs.
#### Disadvantages
- The wiki pages and the API spec look and feel like different sites. There is no navigation to help users move between them.
- No obvious fit with either Wikitech, MediaWiki.org, or Meta-Wiki:
- AQS 1.0 user docs live on Wikitech. However, since Wikitech is typically focused on WMF infrastructure docs, Wikitech isn't necessarily a good fit since these are public APIs that may be of interest to a wide community of users, developers, and researchers. In addition, docs on Wikitech cannot benefit from translation.
- Since these APIs are specific to Wikimedia infrastructure and aren't part of the MediaWiki platform, these docs are also not a good fit for MediaWiki.org.
- Typically, Meta-Wiki is the best place for widely relevant, translated documentation, but Meta doesn't typically contain docs that are as technical as these docs.
### 2. Unified static site
In this approach, we would create a standalone static website that incorporates tutorials, guides, and API specs.
#### User experience
Users arrive at a site dedicated to AQS API docs. They can navigate between tutorials, guides, and API specs without leaving the site. For example, see the [Blubber docs site](https://doc.wikimedia.org/releng/blubber/) recently set up by the Tech Docs team.
#### Advantages
- All docs have a consistent look and feel.
- Docs are presented through a cohesive navigation structure.
- Using the static site generator [Vitepress](https://vitepress.dev/) allows us to use a modern theme while creating minimal maintenance burden.
- We can integrate API spec elements with tutorials, providing functionality to test API requests within the flow of a tutorial.
- By displaying API specs through a static site, we can easily switch the tool we use to display the specs if a better option becomes available.
#### Disadvantages
- Only minimal [translation features](https://vitepress.dev/guide/i18n) are currently available for Vitepress, although coupling with the tool used by Codex means that, if they develop an integration with translatewiki, we can make use of it in our docs.
- Edits to the documentation would need to be submitted through our code review system. This is easy and convenient for developers but not for all users of the docs.
- Because the docs are not part of a wiki, they are not as easy to discover as if they were stored on wiki.
## Proposal
To provide the best experience for users of the APIs, we recommend option 2: unified static site. OpenAPI specs are powerful tools, but they don't integrate well with MediaWiki at this time. By using a static site for the docs, we can present the docs in a polished and cohesive way. We can also make the sandbox feature of the API specs an integrated part of the docs, making it easier for users to get started with the APIs.
Although there are many static site generators available, we recommend using [Vitepress](https://vitepress.dev/) for consistency with the Codex docs. Sharing a tool across documentation projects reduces overall maintenance burden and creates a consistent user experience.
Although contributing to the docs will not be as easy on a static site as it would be on a wiki, the process to add a new AQS API to the docs will be significantly simpler since you will only need to add a few pages to the static site instead of setting up the wiki content and the API spec separately.
To make sure that the static docs site is discoverable from the wikis, we can create wiki pages that appear in search results and direct users to the docs site.
## Decision
Use approach 2, and build a unified static site for the AQS user documentation.
## Consequences
The Tech Docs team will create a Vitepress site on GitLab to host the AQS user documentation. Tech Docs will design an information architecture, create the content, and set up the build pipelines to publish the site to doc.wikimedia.org. The Tech Docs team will also set up wiki pages to help users discover the docs using on-wiki search.
Everyone on Data Products will have edit access to the repository to contribute to the site and the documentation, and Tech Docs will own critical maintenance tasks for the site going forward, including critical software updates and major bugs. Teams creating new AQS APIs will be responsible for adding docs to the site, with Tech Docs available to review and provide feedback.
As a result of this approach, users will have a cohesive experience for reading the docs and experimenting with the APIs.
```lang=irc
[16:20] < taavi> what's up with that toolforge-push email?
[16:27] < dhinus> I was also wondering. it looks like it's a pretty old github account https://github.com/toolforge-push
[16:27] < bd808> It wasn't me. The "firefox" tag on it made me think it wasn't Phorge either (which is where the credentials are properly used)
[16:28] < bd808> The account is used from Phorge (phabricator) to mirror repos into the toolforge GitHub org account
[16:28] < bd808> https://github.com/toolforge/
[16:28] < bd808> https://github.com/toolforge/admin is an example of a repo that those credentials are used to keep updated
[16:31] < bd808> The account is wired into phabricator in places like https://phabricator.wikimedia.org/source/tool-admin-web/uri/view/18249/
[16:32] < dhinus> thanks bd808, do you know of other people who interacted with that account in the past?
[16:32] < bd808> just me.
[16:32] < dhinus> is the password shared somewhere?
[16:33] < bd808> It may be in the SRE pwstore? I can't remember if I gave it to Brooke os someone for safekeeping there
[16:33] < bd808> *or someone
[16:34] < bd808> I "own" the toolforge-push and composer-rate-limits-suck github accounts today
[16:35] < bd808> the https://github.com/composer-ratelimits-suck account is used in Jenkins
[16:38] < bd808> T242898 has some historical info related to the push account. The account and the service it facilitates are things I should have documented on wikitech. I'll make myself a task to do that.
[16:38] < stashbot> T242898: Mirroring Diffusion repositories to GitHub seems to be broken - https://phabricator.wikimedia.org/T242898
```
Semi-related things from the past:
* {T242898}
* {T143969}
We recently component guidelines to the docs, a herculean effort by our design team that migrated existing content from the DSG and involved the creation of a huge amount of new content. Now that this content has been written and included in the docs, we should review component pages for consistency and clarity of structure and language, to ensure that our users have a smooth and consistent reading experience across all components.
### Areas for review
#### Component naming and casing
A decision on how to handle this will be made in T361285. We are mixing casing of component names (text input vs. TextInput) and component properties (primary progressive button vs. Primary Progressive Button). This can be confusing, especially because capitalization changes the meaning of some things, and is needed to differentiate between things that have the same name, such as the Button component and the button element.
#### Pluralization
We sometimes mix singular and plural, such as in this example:
> Avoid using buttons when:
> - The action is to navigate the user to a new resource, which would take them away from the current context. In such cases, consider Link instead.
Instead, we should err on the side of referring to a single component in most cases (e.g. replace "buttons" with "a Button" in the example above). The exception will be components that are usually used in groups, such as Radios or MenuItems. We should still use singular when referring to a single component usage, but may use plural when talking about using a group of components.
#### Dos and don'ts
We often us "dos and don'ts" on component pages to list out things you should and should not do. The design of these sections is meant to start with a "Do:" or "Don't" label, then a list of items that are assumed ot start with that word. For example:
{F43691121}
Sometimes, the text in the list does not follow this structure, which could be confusing. These examples should be udpated to flollow the right pattern. For example:
{F43691162}
In the first example, the "Do" text does not sound like it starts with the word "Do." In the second example, the "Don't" text does not follow this structure either.
== Background
Let's settle on how we refer to components in our docs, we’re mixing them at the moment. We don’t follow any way consistently though.
In a recent comment on a patch by @bmartinezcalvo, @AnneT raised a point about uppercasing only at begin of sentence for consistency. The currently worked on patch by @DTorsani-WMF goes into an also already introduced casing in a different direction.
Example from current docs:
- Normal buttons have three variants (“flavors”)
But then we’re uppercasing also the weight/variant etc in order to separate and make clear that its describing an attribute of the component:
- Use Quiet Buttons to emphasize Normal Buttons when both are combined on the same page.
And the plot is getting thicker when talking about components like:
- The primary action should be represented by a Primary Progressive Button.
While when talking about the concept of a component, more than the component itself, we’ve lowercased again:
- Reserve destructive buttons for actions that involve removal or limitation, such as deleting a page or blocking a user. Avoid using them for actions like cancel buttons.
== Goal
Choose one way and follow it consistently in our public docs and code comments
== Open questions
Which of the following options/ways to take?
# Uppercasing first-letter when talking about the Codex component, and lowercasing when speaking of the general concept. E.g. “Use **Quiet Buttons** to emphasize **Normal Buttons**… cancel **buttons**”. That would be my suggestion.
# Uppercasing only components, never attributes/props, e.g. “Use **quiet Buttons** to emphasizes **normal Buttons**… cancel **buttons**”
# Uppercasing only beginning of a sentence, e.g. “Use **quiet buttons** to emphasizes **normal buttons**… cancel **buttons**”
Please note, that
- uppercasing results in a different pronunciation in screen readers, helping them to understand the component concept.
- there’s research has shown that uppercasing helps increase readability, an insightful SO thread
== Background
For marketing reasons and information architecture clarity it seems useful to add a subdomain codex.wikimedia.org for our design system #codex.
The current content on https://doc.wikimedia.org/codex/ is highly disturbing, it’s only understandable for tech-savvy folks. On the other hand, https://doc.wikimedia.org/codex/latest is not crystal clear/any more self-explaining as virtual root of the Codex docs either.
=== Open questions
# Evaluate design.wikimedia.org/codex as alternative to codex.wikimedia.org
# Should this forward to https://doc.wikimedia.org/codex/latest/ or be self-contained?
== Goal
Add codex.wikimedia.org
```lang=php
/**
* Controls whether stderr should be included in stdout, including errors
* from wrappers. Default: don't include.
*
* @param bool $includeStderr
* @return $this
*/
public function includeStderr( bool $includeStderr = true ) {
$this->includeStderr = $includeStderr;
return $this;
}
```
Should the docs be fixed, or the default inverted?
```lang=php
/**
* Executes command. Afterwards, getExitCode() and getOutput() can be used to access execution
* results.
*
* @return UnboxedResult
* @throws Exception
*/
public function execute(): UnboxedResult {
```
https://github.com/search?q=repo%3Awikimedia%2Fmediawiki-libs-Shellbox+getExitCode&type=code exists, but https://github.com/search?q=repo%3Awikimedia%2Fmediawiki-libs-Shellbox%20getOutput&type=code doesn't.
Is `getOutput()` supposed to be `getStdout()` and/or `getStderr()`?
As part of {T349039} and setting up JSDoc for the CommunityConfiguration extension, look into how we can document Vue components using JSDoc.
- Code example: https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/CommunityConfiguration/+/fc65d70a0af2109969975759342a21e091bdefa5/resources/ext.communityConfiguration.Editor/lib/json-form/controls-codex/src/mediawiki/MultiPageTitleControl.vue
- Goal: Generate at least the props and events tables, similar to https://doc.wikimedia.org/GrowthExperiments/master/js/frontend/demos/onboarding-dialog.html
Now that ResourceLoader's `CodexModule` class supports basic code splitting, we should deprecate the `codex-search` and `codex-search-styles` RL modules so that we can eventually remove them.
However, in order to do that, we should make sure that the Codex page on MediaWiki includes some clear instructions for how to use code-splitting (in both CSS-only or CSS and JS features). The deprecation notice we add in RL could point directly to the appropriate section of this page.
=== Acceptance Criteria
- [ ] Update the https://www.mediawiki.org/wiki/Codex page to include clear instructions/examples on how to use code splitting
- [ ] Add a `deprecated` line in RL for `codex-search` and `codex-search-styles`
# Overview
We added new color tokens to Codex for night mode (T358032). Let's include these colors in the docs https://doc.wikimedia.org/codex/latest/style-guide/colors.html
## Acceptance Criteria
For each color that is added to the docs:
- [] Confirm with designers the WCAG conformance level (AA, AAA)
- [] Confirm the HSB (Hue, Saturation, and Brightness)
- [] Add the agreed on colors to the doc
# Overview
Due to changes in the codebase [insert tasks], we can update the documentation of Pixel (VRT) and maybe PatchDemo since it no longer uses the extension VueTest.
Docs to update:
- https://www.mediawiki.org/wiki/Design_System_Team/Codex_Manual_Testing_Guidelines
- https://www.mediawiki.org/wiki/Design_System_Team/Test_environments#MediaWiki_integrations
## Acceptance criteria
- [ ]
In T358790 we added a section to the [[ https://doc.wikimedia.org/codex/main/style-guide/constructing-forms.html | form building guidelines ]] to explain the difference between `readonly` and `disabled` states for TextInput and TextArea.
The following were some improvements suggested as follow up to that task:
[] This should be its own section (h2) so that it shows up in the "On this page" navigation.
[] Link to the TextInput and TextArea component pages from within this section.
[] Link to this section from the Interaction States sections in TextInput and TextArea components pages.
## Background
In {T358844} we don't currently support the `read-only` attribute in the Field component, for 2 reasons:
- The Field component's parts (label, description, help text, message, etc) do not change at all when an input is `read-only`. So there is nothing to do inside the Field component to handle a `read-only` state.
- Only 2 components support the readonly attribute (TextInput and TextArea), so the `read-only` would be available when these components are being used within a Field.
Since the Field component itself doesn't support the `read-only` state, we need to remove it from:
- [[ https://www.figma.com/file/KoDuJMadWBXtsOtzGS4134/%E2%9D%96-Codex-components?type=design&node-id=10193-109478&mode=design&t=vlLizXLyq4kxWcbd-11 | Figma spec > Interaction States ]]
- [[ https://doc.wikimedia.org/codex/main/components/demos/field.html#interaction-states | Guidelines > Interaction States ]]
We will indicate in both Figma and Guidelines that `read-only` state is just possible in TextInput and TextArea when the Field contains them.
### Open questions
// Add here the questions to be answered in order to design and implement the component //
### Acceptance criteria (or Done)
[x] Remove the `read-only` state from [[ https://www.figma.com/file/KoDuJMadWBXtsOtzGS4134/%E2%9D%96-Codex-components?type=design&node-id=10193-109478&mode=design&t=vlLizXLyq4kxWcbd-11 | Figma spec > Interaction States ]]
[] Remove the `read-only` state from [[ https://doc.wikimedia.org/codex/main/components/demos/field.html#interaction-states | Guidelines > Interaction States ]] //(This will be completed in T358860)//
The "Hosting a model" instructions on [[ https://wikitech.wikimedia.org/wiki/Machine_Learning/LiftWing#Hosting_a_model | this page ]] do not mention any requirements for licensing of the code or requirements for the open source nature of the code.
This task is to consider adding those requirements to the deployment documentation.
Bonus task: Add a link for the hosting a model documentation to the ML team homepage
For the 2024 Hackathon, @JorisDarlingtonQuarshie and @TBurmeister want to make it easy for tool developers and technical contributors to improve tool documentation. To facilitate that, we're working on the following coordination tasks:
[x] Creating a project page: https://www.mediawiki.org/wiki/Doc_Your_Tool:_Creating_user-friendly_documentation
[x] Investigate methods for identifying tools that could use documentation or maybe have it but it's not easy to find, maybe https://toolhunt.toolforge.org can be useful here
[x] Creating (or updating) guidelines about:
-- [[ https://www.mediawiki.org/wiki/Documentation/Contribute/Filing_documentation_tasks | how to file good docs tasks ]]
-- what is [[ https://wikitech.wikimedia.org/wiki/Help:Toolforge/Developing_successful_tools#Write_some_docs | essential documentation for tools ]], focusing on README and CONTRIBUTORS contents, like a "how to run this tool" section
-- how to find and improve existing tool documentation: https://www.mediawiki.org/wiki/Doc_Your_Tool:_Creating_user-friendly_documentation/Instructions
-- how to invite contributions for tool documentations for tools you maintain (building on discussions at past hackathons like T332876, T333178
For practical reasons, we're limiting the scope of this to active tools available on Toolforge, with preference for community-maintained tools. And we're focusing only on technical documentation -- not tool user documentation. If you know of actively-maintained or still-functional tools that could benefit from improved technical documentation, you can contribute to preparing this hackathon project by filing phabricator tasks and tagging them as described above. If I have tagged a task that you think doesn't meet our criteria, or you want it removed for any reason, please remove the tasks. Thanks!
## Background
We need to update the [[ https://www.mediawiki.org/wiki/Design_System_Team/Design_System_Governance_Model#Model_Flowchart | Governance Model ]] to represent the flows when product teams design/implement custom components exclusive for their projects, which won't be part of Codex components. While the DST focus remains on supporting the creation of new Codex components, these custom components will use the Codex guidelines anyway.
These custom components might:
1. Be created as custom components in that project and not be reused more.
2. Be created as a custom component in that project and then be reused in other projects (in this case, we will need to decide if they can be included as Codex components).
### Governance model
| Updated governance model |
### Open questions
[] Given that these custom components must follow to Codex guidelines, even though they won't be implemented as Codex components but rather as custom components within individual product projects, should we document this creation process on the [[ https://doc.wikimedia.org/codex/main/contributing/overview.html | Codex site ]]?
### Acceptance criteria (or Done)
[] Update the governance model including the flows commented above
[] Validate the governance model with the DST
[] Update the governance model and steps in [[ https://www.mediawiki.org/wiki/Design_System_Team/Design_System_Governance_Model#Model_Flowchart | Mediawiki ]]
== Background
**Steps to replicate the issue** (include links if applicable):
* Visit a page on the docs site that has a sidebar menu (example) on mobile
* Click the "Menu" button on the left
**What happens?**:
The sidebar menu overlaps with the header menu:
{F41830542 width=full}
== Goal
{F41830546 width=full}
As a user
I want to have access to the following information on the dashboard:
[] List and number of Phabricator tasks that mention the page
[] General page information, page categories, incoming and outgoing links (only for individual pages), numbers of incoming and outgoing links (aggregated for the entire page pile).
So that I can reason about the quality of pages and collections
Integrate dashboard's localization mechanisms with translatewiki.net
Placeholder for features to be implemented after the MVP
As noted in parent ticket, many sections of [[ https://wikitech.wikimedia.org/wiki/Search | the wikitech search docs ]] are out of date. Some (but not all) needed changes are related to the Search Update Pipeline.
Creating this ticket to review the docs and update according to recommendations:
**SUP**
- ` Multi-DC Operations` should perhaps talk about streaming updater multi-dc operations. Needs updating regardless of SUP.
- `No updates` should talk about where to look to verify streaming updater operation
**Other**
- `Restarting a node` is outdated, talks about using `es-tool`. Should be updated to reflect cookbooks?
- `Pool Counter rejections` could probably point to the dashboards
- Docs mention `scripts/check_indices.py` from CirrusSearch, this works off the list of writable clusters and thus doesn't work in the new system. Likely the script needs updating.
The page https://wikitech.wikimedia.org/wiki/Analytics/Geoeditors is hard to find and its status as a subpage of "Analytics" doesn't align to the current and evolving structure of the Data Platform docs. Its content should be integrated into docs that are more current and better integrated into the existing page structure. A subject matter expert from the Data Platform group (or someone else with the appropriate expertise) should:
[] Review https://wikitech.wikimedia.org/wiki/Analytics/Geoeditors
[] Move any content that is still correct and relevant into EITHER: https://wikitech.wikimedia.org/wiki/Analytics/Data_Lake/Edits/Geoeditors (if the info is relevant for consumers of the data) OR a subsection (or subpage) of https://wikitech.wikimedia.org/wiki/Analytics/Systems/Cluster (if the info is relevant for producers/maintainers of the data)
[] Add the {{Archive}} template to https://wikitech.wikimedia.org/wiki/Analytics/Geoeditors
Right now, the only source of dataset documentation for the analytics clickstream dataset is https://meta.wikimedia.org/wiki/Research:Wikipedia_clickstream. The page at https://dumps.wikimedia.org/other/clickstream/readme.html points to that Meta page, and to a Figshare page that seems outdated: https://figshare.com/articles/dataset/Wikipedia_Clickstream/1305770.
The Meta page links to https://github.com/ewulczyn/wiki-clickstream which has no additional documentation and also appears outdated.
To make it clear that this is a maintained and current data source, the dataset documentation should be extracted from the historical record of the Research project that created it. It should be discoverable along with [[ https://wikitech.wikimedia.org/wiki/Analytics/Data_Lake/Traffic | similar analytics dataset documentation ]], which currently is on Wikitech.
**Steps to replicate the issue** (include links if applicable):
* go to the official WikibaseLexeme code documentation on doc.wikimedia.org: https://doc.wikimedia.org/WikibaseLexeme/master/php/
* Click on "Topics" in the left sidebar
**What happens?**:
* The url of the page opened is https://doc.wikimedia.org/WikibaseLexeme/master/php/md_docs_2topics_2index.html (note the two "2"s)
* the links to subpages are broken
**What should have happened instead?**:
* The url should have been https://doc.wikimedia.org/WikibaseLexeme/master/php/md_docs_topics_index.html (no "2"s)
* the links should work
**Software version** (skip for WMF-hosted wikis like Wikipedia):
Based on the existing docs, it uses Doxygen 1.9.8
**Other information** (browser name/version, screenshots, etc.):
* Locally, it works as expected with Doxygen 1.9.**4**
* However, tests with Doxygen 1.10.0 also show the error, so it might be harder to fix
* It is still not clear if that is a #upstream Doxygen bug, or an issue with Wikibase Lexeme
* it seems to run the doxygen executable without extra arguments, based on https://gerrit.wikimedia.org/g/integration/config/+/69a52467c2f5b2b75a257c88da6842fcfee75622/dockerfiles/doxygen/run.sh
* In particular, this means that all the links to our official documentation for WikibaseLexeme Lua are now broken everywhere (because https://doc.wikimedia.org/WikibaseLexeme/master/php/md_docs_topics_lua.html is the canonical link in all the on-wiki documentation, announcement emails, etc. Changing that to https://doc.wikimedia.org/WikibaseLexeme/master/php/md_docs_2topics_2lua.html will just mean further breakage once that bug is fixed.)
* This makes it significantly harder to share that documentation with the respective communities, because either we have to share a broken link or a soon-to-be-broken link
===== Background
There is a lack of data for the following dates: 2019.3, 2019.4 and 2019.5 when using the "all-days" value as "day" in mediarequest_top_files dataset (media-analytics service).
For instance: `https://wikimedia.org/api/rest_v1/metrics/mediarequests/top/all-referers/all-media-types/2019/03/all-days`
===== Goal
I would say that the goal should be, at least, to document somewhere this lack of data to inform consumers about it. There is a plan to create some documentation for consumers and it would be a good place to include this. But maybe it's something we should discuss first.
===== AC
[] This lack of data is documented
[] Anything else?
README File etc.
No idea what is available, or not available, and in which state
== Background
With updated VitePress in {T352587} the software features a number of new vars, that are not covered by DST design decisions yet:
```lang=css
--vp-code-block-color: rgba( 255, 255, 245, 0.86 );
--vp-code-block-bg: #292b30;
--vp-code-block-divider-color: #000;
--vp-code-color: var( --color-emphasized );
--vp-code-lang-color: rgba( 235, 235, 245, 0.38 );
--vp-code-tab-text-color: rgba( 235, 235, 245, 0.6 );
--vp-code-tab-hover-text-color: rgba( 255, 255, 245, 0.86 );
--vp-code-tab-active-text-color: rgba( 255, 255, 245, 0.86 );
```
{F41663479 width=50%}
{F41663483 width=50%}
== Goal
Ensure that all code interface parts on the Codex documentation site are using design system colors.
The support channels are getting questions about why some of their templates for thumbnails are breaking. This is because they copy examples from Wikipedia, which still rely on tright etc.
On wikipedia, this works because the styles for the old thumbnails are still included. This is being done by `wgUseLegacyMediaStyles` it seems. This configuration setting defaults to false, but is undocumented on Mediawiki.org and thus not discoverable for most people. The setting also isn't mentioned in any of the release notes as far as I could quickly determine.
We should rectify this.
Recordings have been added alongside Upload Batches as "key concepts" of Lingua Libre, but they currently lack a resource sheet that showcases their usecases, database model, and any other properties that could be useful to know for onboarding developers on the project.
Examples of Resource Sheets:
- [[ https://gitlab.wikimedia.org/repos/wikimedia-france/lingua-libre/lingua-libre/-/blob/main/doc/LOCUTORS.md?ref_type=heads | Locutors ]]
- [[ https://gitlab.wikimedia.org/repos/wikimedia-france/lingua-libre/lingua-libre/-/blob/main/doc/UPLOAD_BATCHES.md?ref_type=heads | Upload Batches ]]
The RecordWizard is divided into "Steps".
Each one of them is developed as a Vue SFC and located in the [[ https://gitlab.wikimedia.org/repos/wikimedia-france/lingua-libre/lingua-libre/-/tree/main/front-end/src/views/record-wizard?ref_type=heads | views/record-wizard ]] folder.
We must document what these steps are, and for each one:
- what they do
- which conditions the user must fulfill to be able to go to the next one (see when they emit `canGoToNextStep` or `canNotGoToNextStep`)
- what should happen if the user comes back to it (?)
- which API calls they use (?)
Additionally, we should also document how to create and implement a new Step.
Examples of Resource Sheets:
- [[ https://gitlab.wikimedia.org/repos/wikimedia-france/lingua-libre/lingua-libre/-/blob/main/doc/LOCUTORS.md?ref_type=heads | Locutors ]]
- [[ https://gitlab.wikimedia.org/repos/wikimedia-france/lingua-libre/lingua-libre/-/blob/main/doc/UPLOAD_BATCHES.md?ref_type=heads | Upload Batches ]]
https://www.mediawiki.org/wiki/Manual:Edit_token has a notice at the top of the page that says "The information on this page needs to be verified by a developer." Based on a cursory review of the revision history, this page's content has likely not been updated in awhile, so it may need more than just a review by a developer...but that would be a good place to start. As is, the notice at the top makes the page appear unreliable and untrustworthy.
Along with a some manual and extension pages, many MediaWiki API pages [[ https://www.mediawiki.org/w/index.php?title=Special:WhatLinksHere/Manual:Edit_token&limit=50&offset=104%7C44708&dir=prev | link to this page ]], including:
- API:Edit
- API:Rollback
- API:Protect
- API:Undelete
- API:Block
- API:Move
- API:Upload
- API:Watch
- API:SetPageLanguage
- API:Options
Anomie made a comment in T241946#5777938 about the minimum standardization level that he tried to make CSS sanitizer follow:
> It appears that prefers-color-scheme is only at the Editor's Draft stage. Ideally we like to wait for at least a Working Draft if not a Candidate Recommendation.
I would like to see this (or any other expectation with consensus - I have a preference toward some version of CR) formalized in the [[https://gerrit.wikimedia.org/r/plugins/gitiles/css-sanitizer/+/refs/heads/master/README.md | library README]]. That way I can stop pointing to thin air/that comment when I leave comments about this concern on specific requests for support of some CSS and just say "here's what WMF has said about the patches it will accept into the codebase".
For reference, the [[https://www.w3.org/2023/Process-20231103/#rec-track | recommendation track]] is currently:
1. Publication of the First Public Working Draft.
2. Publication of zero or more revised Working Drafts.
3. Publication of one or more Candidate Recommendations.
4. Publication of a Proposed Recommendation.
5. Publication as a W3C Recommendation.
This task should be taken to be orthogonal to {T162379} (i.e. strictly about standardization level for draft standards properties) and any change to the README worded as such.
So we know when can eventually drop them...
We don't need to test the PHP serialization any more, and we don't need to test versions as far back as 1.35. Just "the last version" and "the next version" should be sufficient.
Work on T353280 and T343146 is going to create a new/revised set of docs that seek to make it easier for researchers or data consumers to get started using Wikimedia data, and get oriented to the tools and techniques for doing analysis with WMF tools and infra.
When that work is done, we should revise the [[ https://meta.wikimedia.org/wiki/Research:Index | Research landing page and the navigation menu on Meta ]] for this collection to better support navigation to and through those new/revised pages.
As part of improving the data usage documentation, we're working on creating new educational content to help people get started using Wikimedia data to do research. This phab task is for documentation pages on Meta-Wiki, but it relates to other projects the Research org may be working on to create educational modules for researchers.
Part 1 of these docs is focused on understanding the data; that content work is tracked in T343146.
Part 2 of these docs is focused on understanding the tools and techniques for working with Wikimedia data and infrastructure. Initial outline of topics to cover (to be finalized in early 2024):
- Research in the Wikimedia universe
-- Core principles, community practices, what makes a research question answerable, what makes a research topic relevant
-- The analysis workflow: from prototyping to productionizing (and tools to use along the way)
- Infrastructure & tooling
-- …for prototyping & exploration
-- …for processing & large-scale analysis
-- …for sharing & publishing
### Background
This task covers adding a search input that filters items on the All Icons page. It does not cover changing the display of the icons on that page.
See the parent task for design specs.
### Implementation details
- For the input, we could use the IconLookup component, which is part of the `codex-docs` package already. Having autocomplete suggestions would be really helpful.
- Should the icons be filtered as the user types, or only when they select an item in the Lookup?
---
### Acceptance criteria
- [] An input is added to the All Icons page that allows a user to type in the name of an icon and select an option
- [] The icon table updates to only display the selected option (unless we decide that we want to filter the icons as the user types)
## Background
At the moment there are 2 different type of [[ https://doc.wikimedia.org/codex/main/components/demos/card.html#demos | Cards ]] in Codex:
- Non-interactive: they just provide `default` state
- Interactive: they provide different states (default, hover, focus/active)
*Loading state will apply for both non-interactive and interactive cards.
We need to indicate this in the interaction states in both [[ https://doc.wikimedia.org/codex/main/components/demos/card.html#interaction-states | Card's guidelines ]] and [[ https://www.figma.com/file/KoDuJMadWBXtsOtzGS4134/%E2%9D%96-Codex-components?type=design&node-id=6842-69713&mode=design&t=GaViVDcgpSuiur6A-11 | Figma spec ]].
### Documentation
| [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit?disco=AAAA9_t1t4w | Google doc with info updated ]] |
### Open questions
// Add here the questions to be answered in order to design and implement the component //
### Acceptance criteria (or Done)
**Design**
[x] Update the interaction states in both:
[x] [[ https://www.figma.com/file/KoDuJMadWBXtsOtzGS4134/%E2%9D%96-Codex-components?type=design&node-id=6842-69713&mode=design&t=GaViVDcgpSuiur6A-11 | Figma spec ]] in the library
[x] Component's guidelines in the [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit?disco=AAAA9_t1t4w | Google doc ]]
**Code**
[] Update the Card component's guidelines in Codex including the info added in in the [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit?disco=AAAA9_t1t4w | Google doc ]]
Here's a random example:
```
includes/Output/IframeSandbox.php:240 SecurityCheck-DoubleEscaped Calling method \MediaWiki\Html\Html::element() in \MediaWiki\Output\IframeSandbox::getHtml that outputs using tainted argument #2. (Caused by: includes/Html/Html.php +264) (Caused by: includes/Output/OutputPage.php +2988; includes/Output/OutputPage.php +2974; includes/Output/OutputPage.php +2973)
```
I can't for the life of me tell what Phan thinks is being double-escaped here. The code snippet is
```lang=php
public function getHtml(): string {
return Html::element( 'iframe', [
// bunch of attributes
] );
}
```
Is "argument #2" 1-based or 0-based? Is it even claiming that the double-escaping happens in argument #2, or is that only mentioned in passing? Does "outputs using tainted argument" refer to `Html::element` or `IframeSandbox::getHtml`? (I guess the former because the other doesn't have arguments, but the phrasing is ambiguous.) What are the two "Caused by" remarks trying to say?
Now imagine a new developer (who is unfamiliar with Phan and with MediaWiki) having to interpret this error message.
Some ideas of how it could be improved:
* Say what's going on, do not rely on the error code. An error message can't be too verbose of course, but it can include a short URL to a wiki page which explains what this type of error is about.
* Use something more understandable instead of "tainted". (What does it even mean in this context? That it's unsafe input? That it's already escaped?)
* Be clear about 0-based vs. 1-based indexes.
* If the parent method (`IframeSandbox::getHtml` in this case) is only mentioned to orient the reader to where this is happening , and isn't related to the actual problem, move it to the error prefix (after the filename / line number).
* Instead of "Caused by", say something like "Call stack for method1", "Call stack for method 2". Also if the call stack can include method names, that would make it more convenient to follow.
There are (as far as I can tell, haven't done thorough research yet) no docs about how much Harbor quota each tool has, if the quota is per-image, per-tool or both, if there is a process to get more, etc.
In addition, trying to push an image larger than the quota results in an unhelpful raw 413 error.
Sample app that can be used for the tutorial here: https://github.com/blancadesal/flask-vue
## Overview
Based on the design review feedback of [Apps guidelines](https://doc.wikimedia.org/codex/main/style-guide/wikipedia-apps.html), here are some ways to improve this page:
- Add a `border` and `border-radius` around the images (mainly images that are screenshots) to create a distinction between an image with a white background and the content body's white background.
- When the elements are vertically stacked in mobile view (breakpoints smaller than 640px), some of these images are very tall (ie. KaiOS images) and exceed the viewport height. We can discuss ways to create a better user experience. For example, allowing the grid to display on mobile view.
Mobile view
{F41472262}
### Open questions
//Please add questions here//
### Possible solutions
//Please add solutions here//
#### Option 1:
Allow the grid to display on mobile view.
Examples:
iPhone SE
{F41472106}
iPhone 12 Pro
{F41472107}
#### Option 2:
Set a max-height on images.
### Acceptance Criteria
- [] Add a `border` and `border-radius` around the appropriate PNG images (screenshots) that have a white background
- [] `border` of ?
- [] `border-radius` of ?
- [] Discuss with the team a solution to display tall images in mobile view
- [] An engineer will implement the agreed solution
# Overview
The [[ https://doc.wikimedia.org/codex/main/composables/overview.html | Codex composable documentation ]] includes a list of the exported composables that are useful for Codex users. Here are ways we can improve the documentation.
**Purpose**: Continuous improvement.
### Questions
1. Should we consider adding links to the composable docs when mentioned in contributing code docs? For example:
- https://doc.wikimedia.org/codex/main/contributing/contributing-code/developing-components.html#direction-specific-behavior-in-components
### Acceptance Criteria
- [] Update the `import` path of `useFloatingMenu` in this [[ https://doc.wikimedia.org/codex/main/composables/demos/use-floating-menu.html#full-example | example ]]. The path is incorrect and should reflect that the composable is being exported from `lib`. Therefore, the composable should be imported from `'@wikimedia/codex'`.
- [] In this [[ https://doc.wikimedia.org/codex/main/composables/demos/use-computed-language.html#full-example | example ]], remove the `div` that has the `lang` attribute set on it so that the composable can actually do its work (see [[ https://gerrit.wikimedia.org/r/c/design/codex/+/961479/comments/b8d55162_6c52312e | comment ]]).
- [] Add links to components mentioned in the composable docs
Probably could use a full review, but the specific pain point that led to the creation of this task was the vague nature of https://www.mediawiki.org/wiki/OAuth/For_Developers#Authorisation_2
There should be:
* a clearer explanation of what to do;
* a link to proper API docs for the `oauth2/authorize` and `oauth/access_token` endpoints, with all (required and optional) parameters explained
* a link to some actual examples, either URLs or something simple like `curl`
Also maybe move public clients to a separate section?
# Overview
Several Codex components can be wrapped by [[ https://doc.wikimedia.org/codex/main/components/demos/field.html | Field ]] because they are form input types or form elements.
Let's demonstrate how to display the error status in these components within a Field. Using the Field component, Field will pass the error `status` prop set on Field to its children components.
### Questions
1. What components should we consider adding an error-handling demo using Field?
| **Codex Component** | **Has a demo using Field?** | ** Consider adding an error-handling demo using Field?**
| Checkbox | No | Yes
| Combobox | Yes | Not needed - component doesn't have an error state
| Lookup | Yes | Not needed - component doesn't have an error state
| Radio | Yes | Not needed - component doesn't have an error state
| SearchInput | Yes | Not needed - component doesn't have an error state
| Select | Yes | Yes
| TextArea | Yes | Yes
| TextInput | Yes | Yes
| ToggleSwitch | Yes | Not needed - component doesn't have an error state
### Acceptance Criteria
- [] Add demos to the following component's demo page displaying error handling using Field
- [] Checkbox
- [] Select
- [] TextArea
- [] TextInput
This ticket involves the work with expanding [Help:Edit check](https://www.mediawiki.org/wiki/Help:Edit_check) so that it equips volunteers with the information they need to understand Edit check.
=== Stories
- As someone who is reviewing edits and happens upon an edit tag I don't recognize (`editcheck-references-activated`)
- As someone who is hearing about the Edit Check project for the first time
WARNING: @ppelberg to finish drafting the stories above
We should probably create a page (maybe at [[ https://meta.wikimedia.org/wiki/Community_Tech/API_keys | Community Tech/API keys ]]?) which details:
- the API keys which are available for community use (iirc only those for use with [[ https://wikitech.wikimedia.org/wiki/Nova_Resource:Google-api-proxy | google-api-proxy ]]?)
- which tools (and their maintainers) have access to the key
- how to request access to the key
## Background
The [[ https://doc.wikimedia.org/codex/main/components/demos/tabs.html#:~:text=tabs%20have%20a-,Gray200,-background%2C%20with%20the | components guidelines in Codex ]] were documented using the option token's name (e.g. `Gray200`) instead the decision one (e.g. `background-color-disabled-subtle`). After reviewing this within the DST we decided to use the decision token's name and provide a way to link directly to the token where more information about the underlying color can be found.
We will need to update the component guidelines to use decision tokens and link them to the associated token documentation.
### Documentation
| [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit#heading=h.44j4hicgxpd3 | Google doc with the components guidelines ]] |
### Acceptance criteria
**Design**
[] Rename color names from option tokens to decision token in the [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit#heading=h.44j4hicgxpd3 | Google doc ]]
**Code**
[] Update documentation in the Codex site
[] Link the decision tokens to the specific token in the demo once this task is done {T349262}
== Background and goal
How do we want to (if at all) handle guidelines for MediaWiki (or in doubt general wiki) special interaction needs, like “Red Links”? How technology agnostic do we make the descriptions and guidance?
From the [[ https://doc.wikimedia.org/codex/latest/components/mixins/link.html#types | Link guidelines ]]:
> **Red links (aka new links)**
> Links to pages that do not exist yet. These display the color Red600 for both the normal or underlined types.[3]
> **Card**
> Cards can be clickable and offer a way to navigate to the content they represent (e.g. Wikipedia articles).
> **Dialog**
> ![A white overlay separating a dialog from a Wikipedia page.]
> …
> Use of the Dialog component in features which don't rely on SSR (which includes all MediaWiki usage for now) can dispense with this.
> **TypeaheadSearch**
> All references to Wikipedia and Wikidata. TahS has a special position, nonetheless, or even more so we should consider it here.
== Acceptance criteria
[] Identify the best possible way to go forward for Codex, as design system for Wikimedia on wiki agnosticism question
[] Update guidelines accordingly of outcome, by expanding or contracting them
From {T347313}. Initial attempts to solve this on Figma export were unsuccessful.
In the image in the [[ https://doc.wikimedia.org/codex/main/components/demos/tabs.html#interaction-states | Tabs > Interaction states ]] section, the lines within the Tabs component should be 1px for the gray one and 2px for the blue one.
## Background
This task collects possible improvements to the component guidelines in [[ https://doc.wikimedia.org/codex/latest/ | Codex ]].
**High impact:**
- Review the content in each component's demo page and make sure the information is not duplicated in the Guidelines and Demos sections
- The link to the Figma spec sheet in each "Specifications" section is a bit hidden ([[ https://doc.wikimedia.org/codex/latest/components/demos/button.html#specifications | an example ]]). We could emphasize it.
- [[ https://doc.wikimedia.org/codex/latest/components/demos/button.html#progressive-button | Button > Content > Progressive button ]]: the current example is wrong ("Discover more articles") since Buttons are not used for navigating content but for actions instead. We should rename this using actions instead (e.g. "Accept").
- Card: in the "[[ https://doc.wikimedia.org/codex/latest/components/demos/card.html#interaction-states | Interaction states ]]" section just the `with link` version is currently represented. We need to represent both `default` and `with link` cards.
- Combobox:
- The images in the "Specifications" is wrong since the menu displayed needs to be the same width as the input. Update image with this new one [[ https://drive.google.com/file/d/1RwDfw9B6QsZbhERZ-c2Pk3Y77ZjNtnPp/view?usp=sharing | combobox-specifications.svg ]]
- The "No results" state is missing in the "Interaction states". So we need to update the image [[ https://drive.google.com/file/d/1kO7f0mkpiWEoaEtW-vUFivRPV0iP1EGw/view?usp=sharing | combobox-interaction-states.svg ]] and its text description and alt text (updated them in the [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit | doc ]]).
- Link: we refer to the blue link as "Default link" in the component's guidelines while we refer to "Standard link" in the demos. We need to unify its name.
- Lookup: the "No results" state is missing. So we need to update the image [[ https://drive.google.com/file/d/1pqSEKzN6AqU6erhKZwbSKDqn_hPjpsnD/view?usp=sharing | lookup-interaction-states.svg ]] and its text description and alt text (updated them in the [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit | doc ]]).
- Menu: menu orientation upward is not represented in the component's guidelines. We need to include both downward and upward orientations.
- ~~Progress bar: elevated image asset is slightly misleading with the very hard to recognize scaled-down size~~
{F41695285}
- ~~Radio: There is an erratum in the [[ https://doc.wikimedia.org/codex/latest/components/demos/radio.html#specifications:~:text=to%20ensure%20consistency-,withthe%20body%20text,-.%20It%20can%20also | Specifications > Label ]] text (missing space in "withthe")~~
- [[ https://doc.wikimedia.org/codex/main/components/demos/tab.html#content | Tab > Content ]]: we need to update the Do and Don't images since the lines below the selected tabs are wrong. Also, this content recommendations could fit better within the Tabs component instead, since "Tab" is just for the tab items.
- ToggleButton: include the "Content" section to explain about how to write content for these Toggle Buttons (as we do with Button component). //"Use short, precise verbs, ideally with fewer than 38 characters for English. The average character length of language translations is 42 characters."//
- {T355415}
- {T357429}
- {T359647}
**Medium impact:**
- Color's documentation: decide if we want to use the option token's name (e.g. `Gray200`) or the decision one (e.g. `background-color-disabled-subtle`)~~ To be discussed in a future DST Design/Eng sync instead of creating a task
- Evaluate if we want to remove the "Interaction states" section from the guidelines
- Evaluate if we want to rename the "Specifications" section to "Anatomy"
- Ensure that we only use DS components in our imagery. We currently feature buttons (and illustrations) that are not part of our DS {F41693817}
**Low impact:**
- References section: just the components moved from the DSG contain a "References" section. We need to review the [[ https://docs.google.com/document/d/1ijapYGCW_0MP3PT5A6DyDooUtcq_ndp4gbK1-A3io7k/edit#heading=h.uteb407jne6h | new Codex components ]] list and include references when needed
- Also decide where to put the References, if we continue with it. Right now it's hanging in the air underneath Guidelines, where the more natural expectation would be to have it end of page.
- If References, then add direct link references, not links to the heading. For satisfying UX and a11y needs: See https://gerrit.wikimedia.org/r/c/design/codex/+/959603/14/packages/codex-docs/component-demos/button/button.md for example. We put in a enumerated list of Reference ids, otherwise the link is no semantic connection. We can leave this for post MVP.
- We could improve the component's guidelines by adding:
- {T357714}
- {T311671}
---
### Acceptance criteria
[] Evaluate each one of the items in the list above and create subtasks if needed
[] Update the components guidelines in Codex
**Current situation:**
when setting up the test system so that we (engineers and/or PMs) can check some things before the package being released we follow [[ https://github.com/wmde/wikibase-release-pipeline/blob/main/docs/topics/test-system.md | this ]] instructions. All the times that we have done it in the past months we have had to hack and re-check more than it is desired. Not all the info that we would have needed is in the documentation and some of that documentation may also be outdated.
**Acceptance Criteria:**
- documentation is complete, updated and clear so that any engineer from the team can easily(TM) set the test system by following it
As of yesterday, October 6 2023, the tideways_xhprof PHP extension [[https://github.com/tideways/php-xhprof-extension/commit/767fcd7f6a09954a77f48321ea3c7078de694c9b | has been archived ]]. The suggested replacement is the "classic" xhprof extension, which has been made compatible with PHP 7 (and then 8) a few years ago. Even though we primarily use Excimer nowadays (TTBOMK), MW still supports tideways_xhprof and uses it in a bunch of places. Some of them, like [[https://gerrit.wikimedia.org/g/mediawiki/core/+/c80a8d36529d2e86ea95f0e85cd63148714be3dd/includes/profiler/ProfilerXhprof.php | ProfilerXhprof.php]], already support both xhprof and tideways_xhprof, so for them this is just a matter of removing the latter. In places where we currently install tideways_xhprof (e.g., CI, vagrant), we should replace that with xhprof.
- [[https://codesearch.wmcloud.org/search/?q=tideways&files=&excludeFiles=&repos= | Codesearch for "tideways" ]]
- [[https://www.mediawiki.org/w/index.php?search=tideways&title=Special%3ASearch&profile=advanced&fulltext=1&ns0=1&ns1=1&ns2=1&ns3=1&ns4=1&ns5=1&ns7=1&ns8=1&ns9=1&ns10=1&ns11=1&ns12=1&ns13=1&ns14=1&ns15=1&ns90=1&ns91=1&ns92=1&ns93=1&ns100=1&ns101=1&ns102=1&ns103=1&ns104=1&ns105=1&ns106=1&ns107=1&ns486=1&ns487=1&ns710=1&ns711=1&ns828=1&ns829=1&ns1198=1&ns1199=1&ns2300=1&ns2301=1&ns2302=1&ns2303=1&ns5500=1&ns5501=1 | Pages mentioning tideways on mw.org]]
- [[https://wikitech.wikimedia.org/w/index.php?search=tideways+-intitle%3A%22Server+admin+log%22&title=Special:Search&profile=advanced&fulltext=1&ns0=1&ns1=1&ns2=1&ns3=1&ns4=1&ns5=1&ns7=1&ns8=1&ns9=1&ns10=1&ns11=1&ns12=1&ns13=1&ns14=1&ns15=1&ns110=1&ns111=1&ns112=1&ns113=1&ns116=1&ns117=1&ns498=1&ns499=1&ns666=1&ns667=1&ns828=1&ns829=1&ns2300=1&ns2301=1&ns2302=1&ns2303=1 | Pages to update on wikitech ]]
I just realised by chance that we now have a [[https://gerrit.wikimedia.org/g/mediawiki/core/+/b1725d9a13d99d7cb6b538bf3779258b93fffdd6/includes/htmlform/CodexHTMLForm.php | CodexHTMLForm]]. However, it is not documented in https://www.mediawiki.org/wiki/HTMLForm or any other place that I could think of. I was curious to see how it works in practice, so I tried it in a few places, but it looks like it might be a WIP, given that some fields look incomplete/partially styled. It would be nice to have documentation and a task to follow the progress.
As part of T341364, I created some [[ https://wikitech.wikimedia.org/wiki/Category:Documentation | Documentation subcategories on Wikitech ]] to help with navigation, search, and aligning the content to [[ https://www.mediawiki.org/wiki/Documentation/Toolkit#Use_templates_to_create_documentation | standard templates ]].
I wasn't able to review and apply categories to all the [[ https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS | Cloud VPS ]] docs, so I'm filing this task for anyone who wants to pick it up.
Suggested work is:
1) Review each of the pages linked in the [[https://wikitech.wikimedia.org/wiki/Template:Cloud_VPS_nav | Cloud VPS navigation menu ]].
2) Try to identify if the page aligns with a standard doc type, as defined [[ https://www.mediawiki.org/wiki/Documentation/Toolkit#Use_templates_to_create_documentation | here. ]] For example, if it is primarily a [[ https://wikitech.wikimedia.org/wiki/Category:How-to-guide | how-to guide ]], add that category to the page. ([[ https://en.wikipedia.org/wiki/Help:Category#Summary | Here are instructions for how to add categories to pages ]]).
It's very likely that these pages are a mix of different types of content, and don't align clearly with one doc type or another. This is still useful information. You can tag docs as more than one doc type, and that will help people know that the page probably needs some work to clarify its purpose and make sure it achieves its goals.
As part of T341364, I created some [[ https://wikitech.wikimedia.org/wiki/Category:Documentation | Documentation subcategories on Wikitech ]] to help with navigation, search, and aligning the content to [[ https://www.mediawiki.org/wiki/Documentation/Toolkit#Use_templates_to_create_documentation | standard templates ]].
I wasn't able to review and apply categories to all the Toolforge docs, so I'm filing this task for anyone who wants to pick it up.
Suggested work is:
1) Review each of the pages linked in the [[ https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav | Toolforge navigation menu ]].
2) Try to identify if the page aligns with a standard doc type, as defined [[ https://www.mediawiki.org/wiki/Documentation/Toolkit#Use_templates_to_create_documentation | here. ]] For example, if it is primarily a [[ https://wikitech.wikimedia.org/wiki/Category:How-to-guide | how-to guide ]], add that category to the page. ([[ https://en.wikipedia.org/wiki/Help:Category#Summary | Here are instructions for how to add categories to pages ]]).
It's very likely that these pages are a mix of different types of content, and don't align clearly with one doc type or another. This is still useful information. You can tag docs as more than one doc type, and that will help people know that the page probably needs some work to clarify its purpose and make sure it achieves its goals.
https://dumps.wikimedia.org/ and https://meta.wikimedia.org/wiki/Data_dumps seem to be the primary landing pages for Dumps as a product/service. These pages could be improved to be more effective and user-friendly.
Without having done an in-depth review, the major opportunities I see here are:
- Choose one page/platform to serve as the landing page for dumps, and make that landing page follow best practices like providing task-based navigation, organizing content into easily-consumable units, and using progressive disclosure to guide users to more detailed information. https://meta.wikimedia.org/wiki/Data_dumps is providing links to a lot of great information, but it is overwhelming and should be audited to make sure it's linking to reliable and relevant resources.
- Consolidate duplicate information scattered on multiple pages/wikis/platforms
- Restructure pages and add navigation based on audience and critical user journeys / data tasks. Figure out a way to provide clear and consistent navigation between all the different places where there's dump related content, like...
https://www.mediawiki.org/wiki/SQL/XML_Dumps
Pages linked from https://meta.wikimedia.org/wiki/Data_dumps/More_resources
https://gitlab.wikimedia.org/repos/research/html-dumps/-/blob/main/README.md
Pages at https://meta.wikimedia.org/wiki/Category:Data_dumps
https://wikitech.wikimedia.org/wiki/Dumps
- Standardize language for how we refer to the various data sources and content of the dumps. For example, when I look at https://meta.wikimedia.org/wiki/Data_dumps/What%27s_available_for_download I have a hard time aligning that with what I see at https://dumps.wikimedia.org/
Related docs tasks (that I'm aware of; there are likely more that I didn't yet find):
{T193296}
{T343146}
https://wikitech.wikimedia.org/wiki/Portal:Data_Services could function more effectively as a [[ https://www.mediawiki.org/wiki/Documentation/Portal_pages | portal page ]] if it was shorter and used a layout that is more navigation-focused. There may also need to be some clarification about which of the products/services linked on this page are sufficiently stand-alone to be considered products/services in their own right, vs. features of other products/services like Toolforge or Cloud VPS. Ambiguity about this makes for a confusing user experience because someone navigating from this portal page may not be expecting to be linked into the middle of the Toolforge or Cloud VPS docs when they were navigating in the context of accessing data, and may not be familiar with or be users of Toolforge/Cloud VPS. (For example, from the Wikitech main page directly to this portal page).
Suggested improvements in addition to the above:
* One link per section: only link to one single best page for the products/services being linked to; ideally the link should go to the product/service [[ https://www.mediawiki.org/wiki/Documentation/Landing_pages | landing page ]], not to a very detailed content page.
* Reduce the amount of text to only include 1-2 sentences for basic context; all other text should be on the product/service landing page to which this page links.
* Avoid linking to very detailed content pages from this portal page. As a cross-collection landing page, a portal should link to landing pages that provide a more gentle introduction to the product or service, not to content pages.
* Use a layout grid or other easy-to-skim format that emphasizes the navigational purpose of the page.
[[https://wikitech.wikimedia.org/wiki/Help:Toolforge/Performance|Help:Toolforge/Performance]] has valuable information about troubleshooting and improving performance of web services running on Toolforge. It's written from an SRE perspective focused on performance testing scenarios and identifying improvements for each of them. Some of this type of information is in more visible Toolforge docs, but it would be good to have a single page people could visit to learn about performance improvement and pitfalls to avoid.
1) Check if information in https://wikitech.wikimedia.org/wiki/Help:Toolforge/Performance is still valid. If not, remove it.
2) Remove or relocate all information that is overly-detailed or focused on admins / SREs; refocus the page on what users would need and want to know to test their web services' performance and improve it.
3) Add section content / links to tools that are available to tool developers for monitoring their tool performance, like https://grafana.wmcloud.org/d/TJuKfnt4z/kubernetes-namespace?orgId=1 (?) Others?
4) Contextualize content in other docs by highlighting how [[ https://wikitech.wikimedia.org/wiki/Help:Toolforge/Redis_for_Toolforge | Redis ]] and other Toolforge services can help improve tool performance.
5) Add a link to this page in https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav
It seems like https://wikitech.wikimedia.org/wiki/Help:Resize_root_partition_of_an_OpenStack_hosted_virtual_machine can probably be deleted, but since I'm not sure, I'm filing this task for it.
If it can't be deleted, the content should be moved somewhere else. It's currently only linked from https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS_Instances, but with no context. Maybe it should be considered an admin doc?
As a developer using Toolforge, I shouldn't need to understand Kubernetes as a primary topic; this is backend infrastructure that the platform admins manage for me. The existence of [[ https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes | this doc just about Kubernetes ]] made sense when the team was migrating from Grid Engine to k8s, but now it is problematic because information about running jobs and web services is sharded between existing docs about those topics, and the k8s doc.
1. Move content about running webservices on k8s into [[https://wikitech.wikimedia.org/wiki/Help:Toolforge/Web|Help:Toolforge/Web]]. This includes the [[https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes#Kubernetes_webservices|"Kubernetes webservices"]] section and the [[https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes#Container_images|"Container images"]] section, though the latter may need a cross-ref from the jobs doc if it lives primarily in the web services doc (it's unclear to me how much container images matter for jobs, if at all).
2. Move content about running jobs on k8s into [[https://wikitech.wikimedia.org/wiki/Help:Toolforge/Jobs_framework | Help:Toolforge/Jobs_framework]].
3. Move troubleshooting content into https://wikitech.wikimedia.org/wiki/Help:Troubleshooting_Toolforge.
4. Move information about [[ https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes#Namespaces | namespaces ]] into the [[ https://wikitech.wikimedia.org/wiki/Portal:Toolforge/About_Toolforge | Toolforge concepts overview ]], or include it in both the web and jobs framework docs.
5. Move information about quota and resources into a new doc: T347887
6. Any concepts or info about Kubernetes that is useful for users to know can be added to [[ https://wikitech.wikimedia.org/wiki/Portal:Toolforge/About_Toolforge#Kubernetes_cluster | the k8s section in the Toolforge overview ]].
7. If/when https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes is ready to be deprecated due to this content redistribution: there are many links throughout the Toolforge docs that should be updated -- a simple redirect won't be able to cover all the different final destinations of the content. Also, remove the link from https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav.
As a Toolforge user or prospective user, I want to be able to quickly understand the memory and resources available to me for running my tool(s). I want to know how to monitor my tools' memory and resource usage, how and when to request a quota increase, and things I should consider before doing that.
1. Content in the following sections should be consolidated into one new document:
- https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes#Quotas_and_Resources
- https://wikitech.wikimedia.org/wiki/Help:Toolforge/Web#Runtime_memory_limits
- https://wikitech.wikimedia.org/wiki/Help:Toolforge/Web#Requesting_additional_tool_memory
- https://wikitech.wikimedia.org/wiki/Help:Toolforge/Jobs_framework#Job_quotas
2. Once a new doc is created for all the above content, pieces of it that are relevant to web services or jobs framework can be transcluded into those pages, or the pages can link to the new resources doc. Only include the minimum amount of information necessary -- one goal of this work is to reduce how many times this information is duplicated across the docs.
3. The new doc should include a section that outlines the Quota Increase request process and the considerations that may cause a Toolforge user to request to use [[https://wikitech.wikimedia.org/wiki/Help:Trove_database_user_guide|Trove]].
4. When this new doc is created, it should be linked from the following docs, replacing the current links about the topic:
-- https://wikitech.wikimedia.org/wiki/Portal:Toolforge/About_Toolforge#Shared_services_and_resources
-- https://wikitech.wikimedia.org/wiki/Help:Toolforge#Constraints_of_Toolforge
-- Also, add a link to it in the [[ https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav | Toolforge docs navigation menu ]]
What does permission denied mean?
Permission to what?
How would I go about fixing it?
```
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/urllib3/connectionpool.py", line 699, in urlopen
httplib_response = self._make_request(
File "/usr/lib/python3/dist-packages/urllib3/connectionpool.py", line 394, in _make_request
conn.request(method, url, **httplib_request_kw)
File "/usr/lib/python3.10/http/client.py", line 1283, in request
self._send_request(method, url, body, headers, encode_chunked)
File "/usr/lib/python3.10/http/client.py", line 1329, in _send_request
self.endheaders(body, encode_chunked=encode_chunked)
File "/usr/lib/python3.10/http/client.py", line 1278, in endheaders
self._send_output(message_body, encode_chunked=encode_chunked)
File "/usr/lib/python3.10/http/client.py", line 1038, in _send_output
self.send(msg)
File "/usr/lib/python3.10/http/client.py", line 976, in send
self.connect()
File "/home/reedy/.local/lib/python3.10/site-packages/docker/transport/unixconn.py", line 30, in connect
sock.connect(self.unix_socket)
PermissionError: [Errno 13] Permission denied
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/usr/local/lib/python3.10/dist-packages/requests/adapters.py", line 489, in send
resp = conn.urlopen(
File "/usr/lib/python3/dist-packages/urllib3/connectionpool.py", line 755, in urlopen
retries = retries.increment(
File "/usr/lib/python3/dist-packages/urllib3/util/retry.py", line 532, in increment
raise six.reraise(type(error), error, _stacktrace)
File "/usr/lib/python3/dist-packages/six.py", line 718, in reraise
raise value.with_traceback(tb)
File "/usr/lib/python3/dist-packages/urllib3/connectionpool.py", line 699, in urlopen
httplib_response = self._make_request(
File "/usr/lib/python3/dist-packages/urllib3/connectionpool.py", line 394, in _make_request
conn.request(method, url, **httplib_request_kw)
File "/usr/lib/python3.10/http/client.py", line 1283, in request
self._send_request(method, url, body, headers, encode_chunked)
File "/usr/lib/python3.10/http/client.py", line 1329, in _send_request
self.endheaders(body, encode_chunked=encode_chunked)
File "/usr/lib/python3.10/http/client.py", line 1278, in endheaders
self._send_output(message_body, encode_chunked=encode_chunked)
File "/usr/lib/python3.10/http/client.py", line 1038, in _send_output
self.send(msg)
File "/usr/lib/python3.10/http/client.py", line 976, in send
self.connect()
File "/home/reedy/.local/lib/python3.10/site-packages/docker/transport/unixconn.py", line 30, in connect
sock.connect(self.unix_socket)
urllib3.exceptions.ProtocolError: ('Connection aborted.', PermissionError(13, 'Permission denied'))
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/home/reedy/.local/lib/python3.10/site-packages/docker/api/client.py", line 214, in _retrieve_server_version
return self.version(api_version=False)["ApiVersion"]
File "/home/reedy/.local/lib/python3.10/site-packages/docker/api/daemon.py", line 181, in version
return self._result(self._get(url), json=True)
File "/home/reedy/.local/lib/python3.10/site-packages/docker/utils/decorators.py", line 46, in inner
return f(self, *args, **kwargs)
File "/home/reedy/.local/lib/python3.10/site-packages/docker/api/client.py", line 237, in _get
return self.get(url, **self._set_request_timeout(kwargs))
File "/usr/local/lib/python3.10/dist-packages/requests/sessions.py", line 600, in get
return self.request("GET", url, **kwargs)
File "/usr/local/lib/python3.10/dist-packages/requests/sessions.py", line 587, in request
resp = self.send(prep, **send_kwargs)
File "/usr/local/lib/python3.10/dist-packages/requests/sessions.py", line 701, in send
r = adapter.send(request, **kwargs)
File "/usr/local/lib/python3.10/dist-packages/requests/adapters.py", line 547, in send
raise ConnectionError(err, request=request)
requests.exceptions.ConnectionError: ('Connection aborted.', PermissionError(13, 'Permission denied'))
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/home/reedy/.local/bin/docker-pkg", line 8, in <module>
sys.exit(main())
File "/home/reedy/.local/lib/python3.10/site-packages/docker_pkg/cli.py", line 179, in main
application = builder.DockerBuilder(args.directory, config, select, nocache, pull)
File "/home/reedy/.local/lib/python3.10/site-packages/docker_pkg/builder.py", line 218, in __init__
self.client = docker.from_env(version="auto", timeout=600)
File "/home/reedy/.local/lib/python3.10/site-packages/docker/client.py", line 96, in from_env
return cls(
File "/home/reedy/.local/lib/python3.10/site-packages/docker/client.py", line 45, in __init__
self.api = APIClient(*args, **kwargs)
File "/home/reedy/.local/lib/python3.10/site-packages/docker/api/client.py", line 197, in __init__
self._version = self._retrieve_server_version()
File "/home/reedy/.local/lib/python3.10/site-packages/docker/api/client.py", line 221, in _retrieve_server_version
raise DockerException(
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', PermissionError(13, 'Permission denied'))
```
There is existing information in several docs about the file directory structure within Tool Accounts, file permissions, and how to work with files as a tool maintainer. I think there's enough content that this topic could have its own page, which would make the [[ https://wikitech.wikimedia.org/wiki/Help:Toolforge/Tool_Accounts | Tool Accounts page ]] a bit less overwhelming, while still grouping information together in a way that makes sense.
Suggested content to move out of existing pages and into a new page:
- https://wikitech.wikimedia.org/wiki/Help:Toolforge/Tool_Accounts#Manage_files_in_Toolforge
- Information about per-project, private directories: https://wikitech.wikimedia.org/wiki/Help:Shared_storage#/data/scratch and other sections; with added content or formatting to make it easier to understand what is private, what is shared, and the intended uses for the directories.
- Information about file permissions and related errors or pitfalls, like https://wikitech.wikimedia.org/wiki/Help:Access_to_Toolforge_instances_with_PuTTY_and_WinSCP#Troubleshooting_permissions_errors
- https://wikitech.wikimedia.org/wiki/Help:Toolforge/Developing_successful_tools#Sharing_files_via_packages_or_version_control
For tips and doc templates to help you get started writing a new doc, visit https://www.mediawiki.org/wiki/Documentation/Toolkit
[[ https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS_Instances | Help:Cloud_VPS_Instances ]] duplicates some of the information on [[ https://wikitech.wikimedia.org/wiki/Help:Accessing_Cloud_VPS_instances | Help:Accessing_Cloud_VPS_instances ]] and [[ https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS_user_roles_and_rights | Help:Cloud_VPS_user_roles_and_rights ]].
To improve these docs, there should be a clearer sequence that flows from the introductory docs to the more specific ones. I believe the sequence is:
1) Create basic accounts / developer account
2) Request or join a Cloud VPS project
3) Create instances
4) Manage instances
Content about creating basic accounts shouldn't show up on pages where that step would've had to happen multiple steps beforehand. So, [[ https://wikitech.wikimedia.org/wiki/Help:Accessing_Cloud_VPS_instances | Help:Accessing_Cloud_VPS_instances ]] shouldn't have information about creating a developer account, since that step must be completed before even joining or creating a Cloud VPS project. Creating a developer account should be covered in [[ https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS_project | Help:Cloud_VPS_project ]] or [[ https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS_user_roles_and_rights | Help:Cloud_VPS_user_roles_and_rights ]](but not both). Or, maybe creating a developer account is sufficiently covered on Help:Cloud_VPS and doesn't need to be mentioned again on Help:Cloud_VPS_project.
Whichever doc is the first doc someone should read when they are initially getting set up to use Cloud VPS should:
* Be the first link in the "Get Started" section of the navigation menu, and
* Be linked in the [[ https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS#Get_started | Get Started section at the bottom of Help:Cloud_VPS]].
As we work to produce new XML content dumps, we are creating tables in the `wmf_dumps` hive database. These should be ingested into datahub and documented properly. For now, we can collect tricky or exceptional documentation here so we don't forget.
Some things to document:
[] Document table schema
[] table update cadence
[] data provenance
[] performance characteristics
[] usage of time travel for consistent data.
[] We need at least 16GB on driver to successfully build the query plan for a SELECT over all the table. See T348772#9580824.
===User ID
In our intermediate table, we use `user_id is null` to mean this user is an IP editor. We use `user_id = 0` to mean this user is not existent on this wiki. (more detail in comments)
[] @xcollazo to update existing intermediate table data transformation to reflect this decision.
[] Document minimum executor requirements [1 core, 16GB RAM] to be able to query `wikitext_raw`. See T340863#9407768.
Several issues being reported due to the ORES/LiftWing migration seem to use JavaScript agents even though the issues being reported are caused server-side.
As we work through these issues, it might be helpful to add JavaScript examples to LiftWing API gateway docs just like we did in T343031 for the LiftWing usage docs that only had curl and Python examples.
**Steps to replicate the issue** (include links if applicable):
* Follow the steps mentioned at https://www.mediawiki.org/wiki/Manual:How_to_make_a_MediaWiki_skin to create a new skin for MediaWiki
**What happens?**:
I want to migrate/ update an existing Skin to `SkinMustache`. I am following the steps mentioned at [[ https://www.mediawiki.org/wiki/Manual:How_to_make_a_MediaWiki_skin#Rendering_menus_with_Mustache | Manual:How to make a MediaWiki skin#Rendering menus with Mustache]].
I am trying to show menu items in a specific layout. As per documentation, for showing the menu items I am using `{{{html-items}}}`, but this returns HTML as `li` elements. I want to use some specific classes for the menu items with the `li` and `a` tags. How can I get the individual menu items, urls as data so that I can add custom classes?
**What should have happened instead?**:
I expected the menu items will be available as Data and also will be mentioned in the doc.
**Software version** (skip for WMF-hosted wikis like Wikipedia): 1.40.0
**Other information** (browser name/version, screenshots, etc.):
* Skin Source Code: https://github.com/nasirkhan/mediawiki-bootstrap/tree/SkinMustache
Now that T338834 is done, Codex is available through cdnjs, but there's no documentation about how to use it that way. We should document this, perhaps on the Usage page of the docs site.
We have had two issues come up, T345236 and T346758, that resulted because Codex users were trying to use a component that was released in a version of Codex later than the one they were using, one in MediaWiki, and one via package.json. We should clearly communicate which release each component is included in to prevent this confusion.
### Proposed implementation
- Somewhere on component demo pages, include the version of Codex that component was added in, and the version of MediaWiki that contains that Codex release. For TextArea, that would be something like "Included in Codex v0.13.0+, MediaWiki v1.41+"
- Consider also including that for the CSS-only version
- Include a statement on the design tokens overview that tokens are included in MediaWiki v1.41+
It is possible to change the visible name for the ORES extension, but not the true name.
1. Should we do that? The ORES extension not being powered by ORES is confusing to people when I talk about it, so I am in favor, but could be wrong.
2. If we do change it, we'd need to update some docs to reflect the new name.
We added some code to handle the new 322 / Wallet disabled IPNs from dlocal on this ticket {T341300}
When we get these IPNs, we close down the active subscription so let's add a diagram to show how this works as it spans over two SmashPig and CiviCRM
Current dlocal docs and diagrams are [[ https://wikitech.wikimedia.org/wiki/Fundraising/Data_and_flow/PSP_integrations/dLocal | here ]]
In addition to {T345330}, we should create a subpage that contains technical documentation:
- [ ] set up local development environment
- [ ] technical architecture for features
To better serve as our main Tutorial template in the "Documentation Toolkit", https://www.mediawiki.org/wiki/Documentation/Patterns/Tutorial could use some freshening up and expanding. Specific improvements I think are needed based on a quick review:
* Reduce the list of examples to one or two of the best examples from different wikis
* Clarify the type of content that should go in each of the sections
* Provide links to content templates that can help with formatting, especially for code samples which will likely be most heavily-used in this type of doc.
I created and implemented a first draft of an admin-focused navigation menu. It is based mostly on the contents of [[ https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Admin | Portal:Toolforge/Admin ]] and subpages. Suggested procedure for this task:
- Revise and expand https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav_admin to align with the most useful and common tasks for which Toolforge admins use these docs.
- Apply your template to all the pages that are listed within the template, and to any other pages you consider to be part of Toolforge admin docs, but which may not be used as links in the navigation menu (template) itself.
- Add [[Category:Toolforge_admin]] (it's [[ https://wikitech.wikimedia.org/wiki/Category:Toolforge_admin | a new category ]]) to each of the pages.
- Update the search box in the nav template to use incategory search instead of prefix. (Like [[ https://phabricator.wikimedia.org/T342287#9164578 | this change ]] I made for the user-focused docs)
**The problem**
Over the last two years Amin and myself have done a lot of design work for the IRS, but it’s currently hard to find, especially for someone who wants to learn more about it. I want to 1) make it easier to find and 2) make it easy to understand and follow so that someone can understand at a high level what’s been done and dive deeper if they want.
**The solution**
A Phabricator ticket that links to all design related IRS files. This ticket will be designed for Joydeep to onboard to the project and the team.
== Background and goal
While (public) docs are made compliant with WCAG in T342295, our sandbox isn't fully compliant yet.
Background for this intended changes is, that Codex sandbox could be a one-shop stop for a CI tool for accessibility testing simpler than the demos page.
== Acceptance criteria for done
[] Add an accessible label to MenuItem demo
[] ProgressBars must have accessible name T343312
[] Add 1 icon-only button label
[] Select element must have an accessible name
The documentation on mw.org needs to be updated for the new maintenance runner introduced in T99268. Some pages I found that need to be updated:
- https://www.mediawiki.org/wiki/Manual:Maintenance_scripts only says that run.php should be used, but doesn't say anything more.
- https://www.mediawiki.org/wiki/Manual:Run.php lists the generic script parameters but does not explain, for instance, what "<script>" can be (i.e., class name, path, script name; and the special Extension:Script syntax).
- https://www.mediawiki.org/wiki/Manual:Maintenance_scripts/Running_the_scripts only has a very short note about using run.php, again without additional details, and with all code samples still invoking scripts the old way.
- https://www.mediawiki.org/wiki/Manual:Writing_maintenance_scripts has no mention of run.php and the fact that the boilerplate is mostly unneeded when using it.