Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- ROADMAP.md
- license.txt
- .github/workflows/rolling-release.yml (referenced in README.md)
- info.nut (referenced in README.md)
Contributing to Trans AI involves understanding its role as an automated opponent for OpenTTD. The project utilizes a rolling release model and relies on specific squirrel-based libraries and OpenTTD APIs to transport cargo across various transit modes including road, rail, air, and marine.
Contributors are expected to align their work with the project's ROADMAP.md and adhere to the licensing requirements defined under the GNU GPL v2.0.
Sources: README.md:3-8, README.md:79-82
Development Environment Setup
To contribute code, developers should clone the repository directly into the OpenTTD directory structure to facilitate real-time testing and debugging.
Directory Structure
Developers must place the cloned repository in the following OS-specific paths:
- Linux:
$(HOME)/.openttd/ai - macOS:
$(HOME)/Documents/OpenTTD/ai - Windows:
C:\Users\<username>\Documents\OpenTTD\ai
Sources: README.md:44-48
Managing Versions for Local Development
When developing locally, the versioning in info.nut is handled specifically to prevent conflicts with stable releases downloaded via OpenTTD's in-game content service ('Bananas').
| Component | Logic | Purpose |
|---|---|---|
info.nut | Version set to a distant future date | Forces OpenTTD to prioritize the local source over official releases |
| Rolling Release | YYMMDD format based on commit date | Provides automated daily builds via GitHub Actions |
Sources: README.md:68-75
Contribution Workflow
The project uses GitHub as its primary collaboration hub. The following diagram illustrates the lifecycle of a contribution from issue identification to automated deployment.
The workflow ensures that all contributions are integrated into the rolling release cycle.
Sources: README.md:74-77, README.md:85-87
Requirements for Pull Requests
- Issue Tracker Usage: All bug reports and feature requests must be channeled through the GitHub Issue Tracker.
- License Agreement: By contributing code, contributors agree to license their work under the GNU GPL v2 License.
- Dependency Alignment: Contributions must be compatible with the required libraries:
- AI Library - Common
- AI Library - List
- AI Library - String
Sources: README.md:52-56, README.md:81-83, README.md:85-87
Road Map Alignment
All new features should align with the established roadmap goals. Significant focus areas include expanding transport logic and implementing advanced game concepts.
Cargo Concept Logic
Contributors should aim to implement the "Cargo Concept" (Many-to-one), where the AI attempts to use a single type of industry as a destination for specific cargo types.
| Route Type | Status | Requirement |
|---|---|---|
| Road Route | 50% Complete | Rework needed from current implementation |
| Marine Route | 50% Complete | Rework needed from current implementation |
| Rail Route | Pending | Implementation of many-to-one logic |
Sources: ROADMAP.md:33-40
Feature Priorities
Contributors are encouraged to pick tasks from the following prioritized categories:
- Rail Service: Extending from raw cargo transport to passenger and town-affected cargo chains.
- Special Features: Improving competitor merger logic and bankruptcy prevention.
- API Support: Implementing support for "CargoDist" game mode using available APIs.
Sources: ROADMAP.md:21-28, ROADMAP.md:43-50
Licensing and Legal
The project is strictly licensed under the GNU General Public License version 2.0.
Key Provisions for Contributors
- Freedom to Share: Contributors preserve the right for users to share and change the software.
- Source Code Availability: Any distribution of the modified software must include or provide a written offer for the machine-readable source code.
- Modification Notices: Modified files must carry prominent notices stating that the files were changed and the date of change.
- No Warranty: All contributions are provided "as is" without warranty of any kind.
Sources: license.txt:10-15, license.txt:83-85, license.txt:130-135, license.txt:232-240
Build and Release Process
The project utilizes an automated build system defined in .github/workflows/rolling-release.yml.
The automated process handles the creation of .tar files which are used directly by the OpenTTD client.
Sources: README.md:74-77
Summary
Contributions to Trans AI are governed by a rolling release model and the GPL v2 license. Developers should focus on the Cargo Concept and transport expansions outlined in the Roadmap, ensuring all code is tested within the standard OpenTTD AI directory structure and utilizes the required AI libraries.