User:SRodlund/developing successful tools (staging)

From Wikitech


Overview

This page provides the information you need to develop sustainable tools that can be built upon and maintained and used by the Wikimedia community even if the original developer is no longer able to maintain them.

Prepare to build your tool

Accounts and logins
  • Make sure you have the correct accounts and logins to start working on tools.
  • Learn more
Bastion hosts

There are two bastion hosts to choose from:

  • login.toolforge.org: user login to access tools interactively
  • dev.toolforge.org: user login for heavy processing such as compiles
  • Learn more
Version control
  • Pick the version or source control and code review tools you will use to manage your files.
  • Learn more
Passwords and credentials
  • Keep passwords and other credentials separated from the main application code. Do not expose them publicly in your version control system.
  • Learn more

Add a license

All code in the ‘tools’ project must be published under an OSI approved open source license. A license]] clearly explains if, when, and how others can reuse or build on your work. The license should be documented with a LICENSE or COPYING file in the tool's home directory and header comments in the source code.

Two recommended licenses

GPL-3.0+ license

GPL-3.0+ ensures that all derivative works are made available under the same license terms.

MIT license

MIT Ensure that your original work is mentioned in a derivative project.

Publish the code

Sharing files via packages or version control

  • Package shared libraries using the package manager for your implementation language: PHP Composer packages, Python PyPI packages, Ruby gems, etc. This is the recommended and most portable and future-proof method of sharing code with multiple projects.
  • Shared code can be stored in git submodules, which allow users to keep a git repository within another git repository. Sharing code in this way retains the maintainability and other source controls advantages of git. For more information about git submodules, please see the git documentation.

Sharing files via NFS

Programs running on the job grid and in Kubernetes webservice containers have access to shared NFS directories. This shared access can be used to share files between multiple tool accounts. This is the least portable method of sharing and may not be supported in all future Toolforge services.

  • Access to a tool's code can be delegated to other tools by adding the tools as maintainers of the tool that is hosting the code. This can be done at https://toolsadmin.wikimedia.org/tools/id/<tool>/maintainers/. (It may be appropriate to create a new tool to house the shared code.)
  • Shared config or other files may be placed in the /data/project/shared directory, which is readable (and potentially writeable) by all Toolforge tools and users. In this directory are available, for instance:

Have co-maintainers

Find co-maintainers for your tools who can help out at least with starting/stopping jobs when needed.

Write some docs

Document your tool. This is essential for others to know how it functions and to help maintain it into the future.

Create a page in the Tool: namespace documenting the basics of what your tool does and how to start and stop it.


Add this: https://www.mediawiki.org/wiki/Documentation

Add tool to Toolhub

https://toolhub.wikimedia.org/

Going beyond

Operating in the open is essential to the success of Toolforge projects. Find a way to include this: https://wikitech.wikimedia.org/wiki/Help:Toolforge/Abandoned_tool_policy

Include useful links on a tool's public webpage

If your tool is a web application, you should include some useful links on it for users. For example:

  • Feedback page link,
  • Documentation link,
  • Source code link and license,
  • Authors name(s).

See more ideas and examples in phab:T202949.

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
Stay aware of critical changes and plans
Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)

[[Category:Toolforge|Developing successful tools]] [[Category:Documentation]] [[Category:Cloud Services]]

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=User:SRodlund/developing_successful_tools_(staging)&oldid=2025880"