'''Quick verification''': Always start with <code>make test-mediawiki-simple</code> or the simple test runner to verify core functionality

= Contributing to mediawiki.el =

This file provides guidance to developers as well as tools like [https://claude.ai/code Claude Code], [https://github.com/QwenLM/qwen-code Qwen Code], [https://github.com/google-gemini/gemini-cli Gemini CLI], and others when working with code in this repository.

== Project Overview ==

MediaWiki.el is an Emacs package for editing MediaWiki sites (like Wikipedia) directly from Emacs. This is version 2.4.x, which has been reorganized into a modular structure while maintaining full backward compatibility.

== Common Development Commands ==

=== Testing ===

* <code>make test-mediawiki-simple</code> - Run essential functional tests (8 tests, quick verification)
* <code>make test</code> - Run complete test suite (152 tests total)
* <code>make test-NAME</code> - Run a single test file where test-NAME corresponds with tests/test-NAME.el

=== Development Tasks ===

* <code>make autoloads</code> - Generate autoloader file for the project
* <code>make check-file FILE=filename.el</code> - Check a specific file for balanced parentheses
* <code>make editorconfig</code> - Clean up EOL and EOF whitespace
* <code>make clean</code> - Remove compiled files and artifacts

=== Test-Specific Commands ===

* Individual test files can be run with: <code>make test-FILENAME</code> where test-FILENAME will run the tests found in <code>tests/test-FILENAME.el</code>

== Architecture ==

The package follows a modular architecture with these core modules:

=== Core Module Structure ===

* '''mediawiki.el''' - Main entry point with package metadata and requires all modules
* '''mediawiki-core.el''' - Core variables, constants, and fundamental utilities
* '''mediawiki-faces.el''' - Font-lock face definitions for MediaWiki syntax
* '''mediawiki-font-lock.el''' - Font-lock keywords and syntax highlighting rules
* '''mediawiki-api.el''' - MediaWiki API interaction and data processing
* '''mediawiki-auth.el''' - Authentication and login management using auth-source library
* '''mediawiki-http.el''' - HTTP utilities and compatibility functions
* '''mediawiki-page.el''' - Page editing, saving, and content management
* '''mediawiki-draft.el''' - Draft functionality and temporary editing
* '''mediawiki-site.el''' - Site configuration and management
* '''mediawiki-utils.el''' - General utility functions
* '''mediawiki-mode.el''' - Major mode definition and user interface

=== Key Design Principles ===

* Modular structure with clear separation of concerns
* Full backward compatibility maintained - users can still <code>(require 'mediawiki)</code> and access all functionality
* Each module handles a specific aspect of MediaWiki interaction
* Authentication uses Emacs auth-source library (supports encrypted password storage)
* Uses MediaWiki API for all server interactions

=== Testing Structure ===

* Tests are organized by module in <code>tests/</code> directory
* <code>test-mediawiki-simple.el</code> contains essential functional tests (always run these first)
* Each module has corresponding test file: <code>test-mediawiki-[module].el</code>
* Integration tests verify module interactions
* Extensive mocking to avoid network dependencies

== Important Implementation Notes ==

== ChangeLog ==

Use <code>M-x add-change-log-entry</code> to document your changes in the [[ChangeLog]].

=== Dependencies ===

* Requires Emacs 28.1+
* Uses <code>mm-url</code> for HTTP functionality
* Leverages auth-source for secure password management
* Uses ERT (Emacs Regression Testing) for test suite

=== Security Considerations ===

* Passwords should not be stored in plain text - the package will use auth-source if password is empty
* All network interactions go through MediaWiki API
* Authentication tokens are managed securely

=== Backward Compatibility ===

* All public functions from the original monolithic version remain available
* User configuration and customization variables unchanged
* Existing user workflows continue to work without modification

== Running Tests Effectively ==

# '''Quick verification''': Always start with <code>make test-mediawiki-simple</code> or the simple test runner to verify core functionality
# '''Full testing''': Use complete test suite for comprehensive validation
# '''Module-specific testing''': Individual test files can be run for focused debugging
# '''Test success metrics''': 8/8 simple tests passing indicates successful functionality; full test suite has known acceptable failure rate

== File Organization ==

* Root level contains all module <code>.el</code> files
* <code>tests/</code> directory contains comprehensive test suite with detailed README
* <code>Makefile</code> provides all development commands
* Documentation in MediaWiki format (<tt>.mediawiki</tt> files)