-
Notifications
You must be signed in to change notification settings - Fork 8
How Do I Get Started with the Perl Core Distribution
... with special emphasis on What Do I Need to Do to Work on Perl 7?
We thank you for your interest in helping to develop the next major version of the Perl programming language. The aim of this document is to help get you started at contributing to that community software project.
You will need these physical resources:
-
A desktop or laptop computer or server account that permits you to install software.
-
An internet connection. Almost anything faster than a phone modem should suffice.
The resources you will need depend on which universe of operating systems you plan to work on. Those universes are Unix, Windows and VMS. I have never worked on VMS and have not programmed on Windows in many years. So I will confine my remarks to Unix and hope that others can guide you for Windows. By Unix, we'll mean "Macintosh (Darwin), Linux, FreeBSD or OpenBSD."
On Unix you will need these basic utilities which will either come pre-installed on your machine or which can be installed from central repositories as either packages or ports. (For the purpose of this discussion, we'll elide the difference between packages and ports.)
-
perl (i.e., Perl 5)
-
sh, i.e., whatever is the default shell program for your platform
-
C-compiler (usually gcc or clang)
-
make
-
Command-line utilities such as ls, cd, pwd, grep, sed, sort, head, tail, cat, less, cut and tee. You don't need to be fluent in these utilities, but you will gain fluency using them by participating in this project.
-
git version control system. You should have basic familiarity and be willing to learn more.
-
An account on GitHub. This is all but absolutely essential.
-
SSH keys. If you already have a GitHub account, you should have these already.
-
IRC client. On
irc.perl.orgwe have created the#p7-devchannel and now have a commit bot running there.
In the Perl 5 code repository on GitHub, the core-p7 branch holds code attempting to implement the vision for Perl 7 recently articulated by pumpking Sawyer X. The branch was initiated by Nicolas Rochelemagne (atoomic on irc.perl.org #p5p and @atoomic on GitHub). Working on this experimental branch will give us valuable insights into how Perl might move forward, regardless of whether specific details of Sawyer's vision are implemented or not.
If you would like to assist us in this effort, we would certainly welcome you. You do not have to have previously worked on the Perl 5 core distribution to participate. But to work on any branch in the Perl 5 core you do need certain tools and skills. In this posting we discuss what you need.
For this project you will need to become comfortable in working in two distinct but similar GitHub repositories (or local checkouts) simultaneously. On your machine you should have checkouts of:
You can work with this repository in one of two ways.
-
Simple clone
Go the Code button. Click the disk icon, which will copy the URI for the git-protocol to your clipboard.
Open a terminal and create the directory under which you will store your local git repositories. For example:
$ cd ~ $ mkdir gitworkChange to that directory and clone the repository:
$ cd gitwork $ git clone [email protected]:<insert-your-github-username>/perl5.git perlA subdirectory called perl will be created and the Perl 5 codebase will be downloaded into that directory. This will take a few minutes. When complete, change into that directory, look around and get your bearings.
$ cd perl $ git statusAfter the latter command you should see:
On branch bleadIn most projects on GitHub, the main or default branch in a project's repository is called
master. For arcane historical reasons the name for such a branch in Perl isblead(which rhymes with seed).At this point, you would do well to read the instructions for working on the Perl core distribution which are included in every installation of perl.
$ perldoc perlhackIf you're feeling ambitious, you can now undertake a normal configure/build/test cycle for Perl 5.
$ sh ./Configure -des -Dusedevel && make && make test_harnessBy fetching and pulling from the main repository, you can keep up-to-date with the development of Perl 5.
$ git fetch origin $ git pull origin blead -
Fork, then clone
A simple clone of the Perl 5 repository is good for following along but not quite as good for making contributions to that repository, as you generally do not have write-access to it. You can, of course, submit patches via email (preferred format: patches created with
git format-patch). However, you may find it more convenient to submit a pull request to the main Perl repository from your own GitHub repository.To prepare for this, go back to the main Perl 5 repository and click the Fork button in the upper-right-hand corner of the home page. If you have not previously done this, you will be prompted to select the location to which you want to fork the codebase. Fork it to your own account on GitHub; GitHub will automatically re-direct you there.
Next you need to clone your Perl 5 repository on GitHub to your own machine. You can follow the same steps as in "Simple clone" above.
Go to the Code button. You should then be prompted to Clone with SSH using your password-protected SSH key. Clicking the disk icon will copy the URI for the git-protocol of your repository to your clipboard.
To anticipate, when you want to submit a patch to the repository, you will create a branch on your local machine, write and test the code and documentation, push that branch to your GitHub repository, then submit a pull request from that repository to the main Perl 5 repository.
While Perl 7 development will eventually move in to the main Perl repository, it is currently being done in a repository run by Nicolas R. You should follow the "Fork, then clone" instructions above to first, fork this repository to your own GitHub site, then clone that repository to your local machine.
When cloning that repository to your local machine, we recommend not calling it perl as that is presumably what your local checkout of the main Perl 5 repository is called. Instead, call it something like perl7 or perl-atoomic:
$ [email protected]:<insert-your-github-username>/perl.git perl-atoomicIf you then move into that checkout ...
$ cd ~/gitwork/perl-atoomic... you will see that it is structured just like the main Perl 5 repository.
Should you want to file a bug report about code or documentation in this Perl 7 codebase, you will file it in this repository, not in the main Perl 5 issue queue.
The main (default) branch in the Perl 7 repository is called alpha. This is the branch equivalent to master in most open-source software projects or to blead in Perl 5. It is the branch into which development work will ultimately be merged and from which official releases will be cut.
At any one point in time there is one other important branch in the Perl 7 repository: the objective or working branch. Unlike development in Perl 5, we are organizing our work on this implementation of Perl 7 via a roadmap of specific objectives. Those objectives correspond to goals for Perl 7 set out by the Perl Steering Committee and described on its wiki. We have created an issue in our issue tracker for each of those objectives. For example,
... and so forth. The procedures for working on any objective are described in this wiki document. What's important for now is to recognized that, since we only officially work on one objective at a time, we merge all our commits into the "objective" or "working" branch, test that branch, merge it into alpha only when it's ready, and then cut a new objective branch for the next objective.
As of Aug 08 2020, we're working on Objective 2 ("strict-by-default"), so our objective branch is called alpha-dev-02-strict.
So, when working in the Perl 7 repository, there are two branches which every contributor must keep in mind at all times: alpha and the current objective branch. (This is different from Perl 5, where there is only one branch which all contributors must keep in mind at all times: blead. That's because Perl 5 does not develop by a roadmap or objectives.)