diff --git a/DEVELOPER b/DEVELOPER index fd47ba2e0..639dc84c6 100644 --- a/DEVELOPER +++ b/DEVELOPER @@ -35,9 +35,7 @@ How to Build Taskwarrior General Statement This file is intended to convey the current efforts, priorities and needs of the codebase. It is for anyone looking for a way to start contributing. - While this is biased towards developers, anyone can contribute, and everyone - is encouraged to do so. Here are many ways to contribute that may not be - immediately obvious to you: + Here are many ways to contribute that may not be obvious: - Use Taskwarrior, become familiar with it, and make suggestions. There are always ongoing discussions about new features and changes to existing @@ -55,7 +53,7 @@ General Statement so on, and these may contain errors, or they may not convey ideas in the best way. Perhaps you can help improve it. Contact us - documentation is a separate effort from the codebase, and includes all web sites, and all - are available using git. + are available as git repositories. - Take a look at the bug database, and help triage the bug list. This is a review process that involves confirming bugs, providing additional data, @@ -66,10 +64,10 @@ General Statement - Review the source code, and point out inefficiencies, problems, unreadable functions, bugs and assumptions. - - Fix a bug. For this you'll need C++ and Git skills, but this is one of - the largest ways you can contribute. We welcome all bug fixes, provided - the work is done well and doesn't create other problems or introduce new - dependencies. We recommend talking to us before starting. Seriously. + - Fix a bug. For this you'll need C++ and Git skills. We welcome all bug + fixes, provided the work is done well and doesn't create other problems or + introduce new dependencies. We recommend talking to us before starting. + Seriously. - Add unit tests. Unit tests are possibly the most useful contributions of all, because they not only improve the quality of the code, but prevent @@ -88,11 +86,6 @@ General Statement already rejected such a feature for some very good reasons. So please check first, so we don't duplicate effort or waste anyone's time. - - Donate some server time to the testing effort, by participating in the - continuous integration of all changes, with our Flod software. See this - page for an example: http://central.tasktools.org. Ask us about running a - Flod satellite, we're always looking for exotic platforms to test on. - - Spread the word. Help others become more effective at managing tasks. - Encouragement. Tell us what works for you, and what doesn't. Tell us about @@ -102,25 +95,6 @@ General Statement missing from the software, but gives us insights into how you use it. Plus, you might get your feature implemented. - Next are some specific areas that need attention. - - -New Code Needs - This is code that needs to be written. - - - Need an external script that can locate and correct duplicate UUIDs in the - data file, as found by 'task diag'. This should check to see if there is - a suitable UUID generator installed. This should also be careful to - properly handle recurring tasks. - - Take a look at: - - https://bug.tasktools.org/browse/EX - - This 'extension' release is a collection of all the requested features that - lie outside of the core product, and will be implemented as external scripts - by anyone who wishes to participate. - - Unit Tests Needed There are always more unit tests needed. More specifically, better unit tests are always needed. The convention is that there are four types of unit test: @@ -150,6 +124,27 @@ Unit Tests Needed Note that all new unit tests should follow the test/template.t standard. +Patches + Patches are encouraged and welcomed. Either attach them to the appropriate + Jira issue, or send them to support@taskwarrior.org. A good patch: + + - Maintains the MIT license, and does not contain code lifted from other + sources. You will have written 100% of the code in the patch, otherwise + we cannot maintain the license. + - Precisely addresses one issue only. + - Doesn't break unit tests. + - Doesn't introduce dependencies. + - Is accompanied by unit tests, where appropriate. + - Is accompanied by documentation changes, where appropriate. + - Conforms to the prevailing coding standards - in other words, it should + fit right in with the existing code. + + A patch may be rejected for violating any of the above rules, and more. + Bad patches may be accepted and modified depending on work load and mood. It + is possible that a patch may be rejected because it conflicts in some way with + plans or upcoming changes. Check with us first, before sinking time and effort + into a patch. + Current Codebase Condition 'master' branch: diff --git a/EXPOSITION b/EXPOSITION deleted file mode 100644 index a7d4a03a5..000000000 --- a/EXPOSITION +++ /dev/null @@ -1,232 +0,0 @@ -Startup - On startup, main creates a global Context object, then calls the - Context::initialize and Context::run methods. - - Context is a large object that holds all task information, both in terms of - the task data, and intermediate run-time data. Having one global Context - object means we don't have 50 global variables. Context is therefore just a - big global bucket of data. - - Context::initialize sets up all the data and processes the command line. The - initialization process is a big chicken-and-egg problem, because the command - line depends on configuration (aliases) and the command line can force a - reload of configuration (rc:foo). This is solved by look-ahead: the command - line is scanned for 'rc:xxx' and 'rc.data.location:xxx' arguments, then later - for overrides. - - The Context::run method handles all the debug output and exceptions. Its - main purpose is to set up exception handling and call Context::dispatch. - - -Command Line Parsing - Command line parsing is difficult because of lots ambiguity. The solution is - to make multiple passes over the command line. For example, the command - determines whether subsequent arguments are interpreted as part of a filter or - set of modifications. - - The CLI2 object is fed command line arguments, then through a succession of - calls builds and annotates a parse tree. To help with this, the Lexer is - used to break up strings into tokens. - - The object of the command line parsing is to expand all syntactic sugar to - use the low-level syntax, and expand the boolean logic in filters and create - a well-formed algebraic expression. For example, this command line: - - task 1-10 +foo lis - - is expanded internally to something like this: - - task ( ( id >= 1 and id <= 10 ) and tags._hastag_ foo ) list - - Note that there are concerns with id ranges, operator precedence, tag - checking, and the expansion of the command name. The arguments are then - tagged to indicate what part of the command line іt represents, such as a - filter, operator, or command. - - The CLI2 object will be replaced by a generalized parser and grammar. - - -Dispatch - Dispatch is simple: once the command line is parsed, the command is used to - look up a command object, then a call is made to the Command::execute method. - - Context stores an associative map of command object pointers indexed by a - string. This means the 'done' string is an index to the CmdDone object that - implements the functionality. - - -Command Objects - Every task command is implemented by a command object. The command object - provides metadata, usage and one-line help in addition to the ::execute method - that implements the command. The Command base class implements common - functionality. - - -Column Objects - There is a 1:1 correspondence between attributes stored in the data files and - the columns that may be reported. These are represented by column objects, - which are responsible for validating input, measuring space needed according - to various formats, and for rendering data for reports. There is a - ColDescription object that inherits from a Column base class. - - -TDB2 - The TDB2 object is a layered, transactioned I/O manager. Its purpose is to - isolate code from file I/O, locking and parsing details. It is also - responsible for minimizing reads, writes and parsing of data files. - - All input is assumed to be UTF8. All stored data is treated as UTF8. - - -GC - Garbage Collection is the process that moves tasks between the pending.data - and completed.data files. It is also responsible for waking tasks out of the - wait state. - - Every command that displays task IDs will cause a GC to be run first, which - minimizes the number of changes necessary to the task IDs. This means that - when a report shows task IDs, those IDs will remain valid while subsequent - write commands are issued. The next report run may show different IDs. - - Minimizing the size of pending.data is important for performance, because it - is the file that is accessed most. - - -Files - The data files used are all kept in the rc.data.location directory, which - defaults to ~/.task. The files are: - - pending.data - completed.data - undo.data - backlog.data - - The pending.data file aspires to contain only pending, waiting and recurring - tasks, but this is only correct after a GC, and before any tasks are modified. - This file tends to be relatively stable in size, reflecting the length of the - task list. - - The completed.data file accumulates data over time, and grows unbounded. - - The undo.data file accumulates changes over time, and grows unbounded. It - provides all the necessary metadata to support the 'undo' command. Deleting - this file has two effects which are to remove the undo capability, and remove - the ability for the 'info' command to show a change history. The undo file - can grow quite large, and it can be argued that only the last N transactions - are worth keeping, where N is about 10. - - The backlog.data file contains an accumulated set of changes that have not - been transmitted to Taskserver. It grows unbounded between 'sync' commands. - If you do not use sync, it is fine to just delete this file to save space. - - -Filter - A filter is simply a set of command line arguments, but is only a subset of - the complete command line. These arguments are extracted from the parse tree - according to whether the command found is a read or write command. - - There is a Filter::subset method for applying a filter to a set of tasks, - yielding a result set. It does this by creating an expression from the - parse tree using the Eval object, then evaluating the expression for each task, - such that the result set contains only tasks for which the expression evaluates - to Boolean true. - - -Eval & Variant - The Eval class evaluates expressions, provided in string form, using the - Variant class to represent data elements. Variant implements all operators - for all Variant types. - - -Sorting - Sorting is performed on a set of tasks. More specifically, the list that is - sorted is a set of numeric indexes to tasks that are stored in a separate - list. This minimizes the amount of data copying involved to just integers - rather than Task objects, but at the expense of one level of indirection. - Memory fragmentation is a bigger problem than the performance of vector - indexing. - - The actual sorting is performed by std::stable_sort, but the compare function - is custom. - - -Render - There are two rendering objects, ViewTask and Table. These both have the - same tabular grid rendering capabilities. Table maintains a 2D vector of - strings to contain the data to be rendered, so it is used for things like the - help command output. ViewTask does not copy data, but assumes all data is - stored externally in a vector of Tasks, which minimizes data copying. - - ViewTask contains projection data in the form of a set of Column objects that - represent the X axis. The Y axis is represented by a vector of tasks. - - The rendering process is complex. It involves dynamically setting column - widths based on (1) available terminal width, (2) the columns to be included - in the output, (3) ability to wrap text for certain columns and (4) the size - of the data to be rendered, which involves added complexity when UTF8 is used. - - The Column objects determine minimum width for a column and the maximum width - which then allows ViewT* to make choices. - - -Test Suite - A strong and diverse test suite is critical to the successful release of any - software. With the complex command set and its many permutations, a test suite - is the only way to ensure quality levels, and guarantee that big changes are - robust. - - It is intended that the test suite continues growing, mostly feature tests. - The test are mostly written in Python. Some tests are written in C++ and all - tests generate TAP output. - - There are currently about 8,000 unit tests, that take only a few seconds to - run on a multi-core machine. - - Taskwarrior uses flod software to automate continuous integration across many - platforms. Code changes are automatically detected, propagated, built and - tested on a variety of participating platforms. Grid testing results are here: - - http://central.tasktools.org/ - - When making code changes, it is important that the test suite be run to verify - that functionality was not broken. - - -Debugging - The 'rc.debug=on' override provides the following additional information which - is useful during debugging: - - - Timing of various components (used to generate the data for the charts at - http://tasktools.org/performance). - - Data load times. - - Terminal size, color capabilities. - - Command line parse tree. - - TDB2 layer and I/O information. - - Additionally, there are other settings (see 'man taskrc' for full details) that - may also be helpful: 'rc.hooks=on|off', 'rc.debug.parser=0|1|2|3', - 'rc.debug.hooks=0|1|2', 'rc.debug.tls=0|1|2|3...'. - - -Patches - Patches are encouraged and welcomed. Either attach them to the appropriate - Jira issue, or send them to support@taskwarrior.org. A good patch: - - - Maintains the MIT license, and does not contain code lifted from other - sources. You will have written 100% of the code in the patch, otherwise - we cannot maintain the license. - - Precisely addresses one issue only. - - Doesn't break unit tests. - - Doesn't introduce dependencies. - - Is accompanied by unit tests, where appropriate. - - Is accompanied by documentation changes, where appropriate. - - Conforms to the prevailing coding standards - in other words, it should - fit right in with the existing code. - - A patch may be rejected for violating any of the above rules, and more. - Bad patches may be accepted and modified depending on work load and mood. It - is possible that a patch may be rejected because it conflicts in some way with - plans or upcoming changes. Check with us first, before sinking time and effort - into a patch. - ---- diff --git a/README.md b/README.md index 1bf742bb5..c3331309c 100644 --- a/README.md +++ b/README.md @@ -19,12 +19,11 @@ Thank you for taking a look at Taskwarrior! Taskwarrior is a GTD, todo list, task management, command line utility with a multitude of features. It is a portable, well supported and very active Open -Source project. Taskwarrior has binary distributions, online documentation, -demonstration movies, and you'll find all the details at: +Source project. Take a look at the site: http://taskwarrior.org -At the site you'll find online documentation, downloads, news and more. +There you'll find online documentation, downloads, news and more. Your contributions are especially welcome. Whether it comes in the form of code patches, ideas, discussion, bug reports, encouragement or criticism, your