Help:Toolforge/Developing successful tools
This page provides tips to help you develop successful tools on Toolforge. If you have useful advice, please share.
Pick a license
All code in the ‘tools’ project must be published under an OSI approved open source license. Please add a license at the beginning!
A clear license is very important. It explains the rights that you are willing to grant to others who want to use or modify the software you built. Based on the general principles of the Wikimedia movement.
To learn more about choosing a license for Wikimedia see Wikimedia movement.
The two easiest options for your licenses are:
- GPL-3.0-or-later if you want to ensure that all derivative works are made available under the same license terms (an older GPL license is used for MediaWiki itself) or
- MIT if you only want to ensure that your original work is mentioned in a derivative project.
https://choosealicense.com/ is a good explanation of differences between many Free and Open Source licenses. Be aware the some of the licenses described there are not OSI approved however, so make sure to check against the OSI list before using a license for your project.
How to add your license to your source code
License your source code and document that with a LICENSE or COPYING file in the tool's home directory and header comments in the source code.
Publish the code
Sharing files via packages or version control
Reusable code should preferably be shared using language-specific package managers, such as PHP Composer packages, Python PyPI packages, or Ruby gems. This is the recommended and most portable approach for sharing code between multiple projects.
Shared code can also be managed using Git repositories and Git submodules, which preserve the benefits of version control and simplify maintenance.
Sharing files via shared storage
Toolforge provides shared storage that can be used to share files and data between tool accounts when appropriate. Shared configuration files and other shared resources may be stored in shared directories, and access to tool account files can be delegated by adding maintainers to a tool.
See Managing and sharing files in Toolforge for guidance on:
- sharing files using tool accounts;
- sharing code through packages and version control;
- using shared storage;
- choosing appropriate storage locations; and
- recommended practices for collaboration
Have co-maintainers
Find co-maintainers for your tools who can help out at least with starting/stopping jobs when needed.
Write some docs
See the Tool Docs guide for templates and guidelines about how to document your tool. This is essential for others to know how it functions and to help maintain it into the future.
Tools hosted on Toolforge should create a page in the Tool: namespace, which either contains documentation or links to the page or repository where you maintain your documentation.
Going beyond
Operating in the open is essential to the success of Toolforge projects.
Things should work on mobile.
Basic descriptions should be clear to people who are less-familiar/non-technical/English-as-a-second-language.
Add your tool to Toolhub.
Planning for success
There are many things to think about when you are planning to build a tool.
Have the accounts you need
Follow the Toolforge quickstart guide to make sure that you have all of the accounts and logins you need to begin developing tools with Toolforge.
Secure passwords and other credentials
Keep passwords and other credentials (OAuth secrets, etc) separated from the main application code so that they are not exposed publicly in your version control system of choice.
We recommend using the envvars service to store credentials and make them available as environment variables for your application.
Stay small
Make many small tools that each do one specific task rather than a catch-all tool that does many different tasks.
Pick the right development environment
If you will be doing heavy processing (e.g., tool test runs), please use the development environment (dev.toolforge.org) instead of the primary login host (login.toolforge.org) so as to help maintain the interactive performance of the primary login host.
The dev.toolforge.org host is functionally identical to login.toolforge.org
Even when running on dev.toolforge.org, your processes may be killed without notice by system administrators or automated watch processes if performance of the shared server is severely impacted.
 | The bastion servers do not have compiler tools such as gcc installed. If you want to compile something, see Help:Toolforge/Troubleshooting#There is no C/C++ compiler. |
Determine which public version control you will use
You'll want to use public version control for your tool. You can learn more about how to use version control with Toolforge here: Help:Toolforge/Version Control in Toolforge.
Pick a programming language
Do you have experience that might help another user? Please share it (or point to it) here!
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:
- Chat in real time in the IRC channel #wikimedia-cloud connect or the bridged Telegram group
- Discuss via email after you have subscribed to the cloud@ mailing list
- Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
- Read the News wiki page
Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself
Read posts about Cloud Services on the Wikimedia Technical Blog. (Older posts can be read from the Cloud Services Blog.)