Project:Wiki/Development

From Gentoo Wiki
Jump to:navigation Jump to:search

This space is a landing page for development and maintenance of MediaWiki features and enhancements added by the Gentoo wiki project. These have been added to increase the suitability of the MediaWiki base for the use of the Gentoo project at large.

Details include front page news items using the {{News}} template, wiki-wide templates such as {{Developer}}, {{Project}}, {{News}}, {{GenericCmd}} (including sub-templates {{RootCmd}}, {{Cmd}}, etc.) and forms such as Form:Developer and Form:Project.

Workflows

Each of the following subsections include wiki maintainer workflows. Following these workflows should help maintainers not miss any steps necessary to improve the existing 'infrastructure' facilitated by wiki admins for the Gentoo community.

Main page wiki news items

Main page news items utilize the protect {{News}} template. Review the template parameters before proceeding.

Workflow processes:

  1. Write up news item and place on the Main Page copy/paste it to the top of Gentoo_Wiki:News.
    • On the Main Page Generally the latest 3 news items are visible...
      • Any more than news entries 3 and the page columns start to look unbalanced, so remove the oldest news entry so that only 3 are listed.
  2. If applicable, remove the old news item and place the new item on the news section of the Developer Central landing page.

Developer and project 'profile' changes

Developer 'profiles' on the wiki consist of a wiki form combined with a developer template. The process workflow of modifying the existing properties, templates, and/or forms:

  1. If necessary, create a new or many new properties of relevant type(s) (URL / Text / etc.) to 'tag' the new data element(s). The "Has Something" syntax should be used.
  2. Modify {{Developer/sandbox}} or {{Project/sandbox}} to accept new parameter(s).
    • It is important to note that this test page will need to be edited via the Edit source link directly. The form edit will not work properly. This is expected.
    • Be sure to assign the data to a property for future queries using the [[Has Something::{{{Value}}}|]] syntax.
    • Test via the Developer profile test or Project test page.
    • If it looks good, then proceed, if not, then continue development iteration.
  3. Once it works as expected, then modify (merge changes into) the production template to mirror the changes made in the sandbox template.
  4. If necessary, modify Form:Developer or Form:Project to accept new parameter(s), etc.
  5. Publish a news announcement with mention of the improvement or new feature on the Main Page. Also consider sending a message to the wiki mailing list. The seventh lesson from popular open source book The Cathedral and the Bazaar is "release early, release often." This applies to documentation as well.
    • Optional: If the change is big enough, a news item could be written for www.g.o, however doing so has not been necessary in the past.

Special considerations

The goal of setting Properties (an extension provided by Semantic MediaWiki) in the Developer and Project templates is for querying the pages for data. They enable the possibility for exporting data to export to www.g.o and potentially other *.g.o sites in the future.

Queries can be also be made using wiki "magic word" which are built-in to MediaWiki:

  • 98 active users.
  • 8,770 articles (number inflated by translations).
  • 172,547 pages (number inflated by translations).

Guidelines

CSS, JavaScript, and wiki templates

When extending and/or improving wiki templates, try to use CSS for text formatting whenever possible. Some of our users run NoScript browser extension, which blocks JavaScript. Adding new JavaScript libraries also requires infrastructure access, therefore CSS styling is the preferred styling method.

That stated, all web assets should be hosted at the appropriate Gentoo owned infrastructure locations, such as assets.g.o or the equivalent.

Testing

This section details testing large, site wide changes. This includes new CSS

wikitest.g.o

The Gentoo wiki team has a separate wiki for test purposes available at https://wikitest.gentoo.org. Broad changes that affect the wiki at large should be thoroughly tested in this environment before deploying to wiki.g.o. This is a publicly visible website, so members of the community can create accounts and perform testing as well.

TODO

  1. Write up instructions for syncing the wiki.g.o production database and extensions to wikitest.g.o.
  2. Write section on setting up a local test wiki instance for infra developers using Docker?

See also