-
Notifications
You must be signed in to change notification settings - Fork 8
Guidelines for Working on the 'alpha' Branch
The alpha branch is a branch in atoomic's github repository which holds work commencing on July 23 2020. This work is aimed at evolving Perl 7 out of Perl 5 by incremental, rigorously tested steps.
For this project, the alpha branch will serve the same function that a branch called master plays in other projects on github and that blead plays in Perl 5. That is, it will be the authoritative branch into which sub-projects conducted in other branches is merged and from which release candidates will be cut. Consequently, our objective will be to have the test suite in the alpha branch always "running GREEN", i.e., always culminating in a grade of PASS. If an individual test file in the alpha branch ever gets graded FAIL ("runs RED"), that will be cause for concern and no new commits to the alpha branch will be made until the file and the suite as a whole once again "runs GREEN." If the FAIL cannot be immediately resolved, then an Issue must be opened at our issue tracker -- but no issue pertaining specifically to the test status of the alpha branch should ever remain open long.
Contributors to this project will submit pull requests from either (a) other branches in this repository, assuming they have commit access; or (b) their own github forks of this repository. All development in this project should be carried on first in branches.
The goal of work in the alpha branch is to produce a Perl core distribution which implements the objectives specified on the Defaults for v7 wiki page. These objectives may change from time to time; hence our goal will also have to be updated from time to time. Overall, the goal for Perl 7 can be described (too) tersely as "better defaults." In the alpha branch, we will step-by-step implement these improvements in Perl's default behavior until the point where we are ready to issue a perl-7.0.0 release after which all new features and improvement in Perl must be conducted in Perl 7, not Perl 5.
Because the term "milestone" has a specific meaning in github projects, we won't use it here -- at least not yet. Instead we will lay out a series of objectives that will guide our step-by-step development. When we reach an objective, we will tag the objective with a tag in the format of alpha-NN, where the <NN> is a two-digit, zero-padded number. The alpha branch begins with tag alpha-00 which coincides exactly with tag v5.32.0 in the existing Perl repository. So when we complete Objective 1, we will tag it as alpha-01.
Other things being equal, our "order of battle" will be determined by the order in which objectives are listed on the Defaults-for-v7 wiki page cited above. We will first bump the Perl major version and get the entire test suite to run GREEN. We will then work through the 3 items in On by default; the 5 items in New keywords on by default; and finally the 5 items in Features not experimental anymore.
Until we complete the above list, we will not merge in or cherry-pick any work being done in the 5.33 development cycle in Perl 5.
Until we complete the above list, we will not introduce any functionality intended to provide interoperability between Perl 5 and Perl 7. Should the Perl Steering Committee decide to add that to the list on that wiki page, we will take up such work only after completing the items listed above. The guts code and the testing code for such interoperability should be segregated from the rest of the codebase as much as possible so that we are not tempted to get tests to pass by inserting something like use p5; or use v5; into a test file in order to induce it to run GREEN.
QA will open a ticket in the Issue Tracker for each objective.
For each objective one contributor will serve as Lead Developer (LD). (At the present time that is likely to be atoomic.) The LD will create a local branch from the most recently achieved tag and write or modify the Perl guts code needed to implement the objective. The LD will then write any new tests needed to test the implementation. The LD will then run the test suite and see if it runs GREEN. If the LD runs into problems, he/she is encouraged to call in others for help. The LD should push the local branch to the repository and notify QA and other contributors that the branch is available for testing on their own machines. (A formal pull request is not needed just yet.)
Commit messages should provide an average Perl developer with enough information to understand why a change had to be made and what principles guided the code actually written to make the change. Commit messages should not be overly long -- but we're not giving out prizes for terseness.
Other things being equal, while branches are being tested or pull requests are pending, each test file needing a change should be addressed in a commit of its own. The subject line for a commit message changing a test file should start with the name of the file -- or, at least, its basename. This will facilitate easy searching of our git log output.
The LD and other developers will be strongly advised to run the full test suite for each pull request in a small variety of configurations, including, but not limited to, unthreaded/threaded, regular/debugging. What turned out to be a major flaw in our development process during most of July 2020 was that we focused on "fixing" tests to run on unthreaded builds but ignored how those "fixed" tests would run on threaded builds. Thus, we built up enormous technical debt by incorrectly narrowing the scope of our testing configurations.
Once our tests for a given objective are running GREEN locally, then we have to figure out how to get them (quietly) into a branch in the main Perl github repository as smoke-me branches. When we do that, we will gain the benefit of the smoke-testing architecture which Perl has built up over a 20-year period. We should not merge any pull request or branch into alpha until we have GREEN results on our more reliable smoke-testing rigs.
To be determined: What, if any, testing we do of the branch against important non-core CPAN distributions, e.g., the "head" of the CPAN river.
Once everything for a given objective is running GREEN, we will create a formal pull request (if we have not already done so), do a final review of that request, approve it, merge it into alpha, tag alpha with the next appropriate label, mark the ticket in the Issue Tracker resolved and begin the dev cycle all over again with the next objective.
Since there may be lags in getting smoke-test results or results from CPAN distributions, the developers will be free to start branches for the next objective while waiting. However, these branches may not be merged into alpha until the previous objective is met and tagged. When that happens, the developer's branch must be rebased on the tagged commit.
Objective: Bump the Perl major version number wherever needed in the code base. No other guts changes except those needed to implement this objective. No changes in the test suite except for a few test files which (probably incorrectly) assume that Perl's major version was fixed for all time at 5.
Acceptance Criteria: The Perl test suite, modified only to accommodate limitations described above, runs GREEN in all major configurations and on all major operating systems for which we can test.
Assignees:
-
Lead Developer: atoomic
-
QA Lead: kid51
-
Additional code review: toddr