On becoming a contributor

[samiam95124]

On becoming a contributor

Pascal-P6 will need contributors or eventually it will die. I don't plan on going anywhere, but then that choice is not up to me. The best contributors are bug fixers. These are people who use the system, but encounter bugs and want to fix them instead of just posting the bug (in "issues") and waiting for me to fix it. These people are my stars.

Contributors come and go

Its a fact of life that contributors are usually only around for a short while. This is de rigueur and I am grateful for any contribution.

In the past, contributors have fallen into two classes: bug fixers and revampers. Bug fixers just want to get a particular bug fixed. Revampers are a completely different issue.

It has become a standard story. Someone want to participate in the project, and wants to add something major, or make major changes. Good! However what has happened is that contributor does not like the way the current code works and wants to change it. Then, when the result does not work, and they want me to fix it.

An example is what occurred with Pascal-P5. A programmer developed a C interpreter for it on his own. That's great! I agreed that was a valuable contribution. Now the problems began. He had simplified the way pint worked to produce decks for his C interpreter. Interesting, but it created a system that was now incompatible with Pascal-P5[1]. I pointed out that this was not necessary, that the C based interpreter could run the pint instruction set as is.

I ended up writing a C based interpreter myself that met the required compatibility. I'm sure annoying the contributor in the process.

There have been other, similar stories with the Pascal-P series.

The moral of the story is that significant changes in the way Pascal-P6 works might be a good idea, but they are not in keeping with the project. Pascal-P6 needs improvements (not rewrites!) that are compatible with it, pass all tests and back the ideas and goals of the project. If not, its not wrong, its just such rewrites are better served by a fork of the project and the work done on that fork, as part of a new and different project.

Guide to contributors

The basic points to good contribution are:

1. Understand the project. Whether the code is good or bad, understand how it works first. I'm a contributor too! Pascal-P is not my original project, it came from Niklaus Wirth's project at ETH. It took a while for me to understand the project. Pemberton's book is a great aid for that, and I am here to help. The "oh so typical" thing is a programmer who performs a cursory look at the code, decides it is not good code, and proceeds to rewrite it in his style without even understanding it completely. Don't be that guy.

2. Submit code changes in kind. Yes. Even imitate the style of the code. Ask yourself if your change looks like the current code or stands out as completely different. We (all the contributors, including me) are not here to rewrite the compiler, but to fix issues or add capabilities. If you look at one of my programs, for example pc.pas in the ./pc directory, you will find my style of programming is completely different than the original style of Pascal-P. I adapt to the original style when working on Pascal-P source code.

3. Test. Run a full regression suite (covered extensively in the Pascal-P6 manual). Test. Test. Then test some more.

4. Submit a pull request. This is a formal review process.

5. Start small. Your major change is going to be much more likely to be accepted if you have a track record of small fixes first.

The hell with it all?

If you don't agree with any part of all of this, there is still a place for you. Fork the repo and please do as you like with that[3]. Just please respect the work done here and don't name your new program Pascal-P6[2].

[1] In fact, I later ended up refactoring the pint code in much the same way as he did. That wasn't the point. It was that it would have been an incompatible pint now instead of incremental changes that led to cmach. That would have required two versions of pint.pas going in parallel for some time.

[2] Yes, this was done. A fork of Pascal-P5 that was completely incompatible was done and named Pascal-P6, even though the documentation clearly stated I was working on Pascal-P6. It was here on github, and became an abandoned project. I requested the keeper of the repo change the name and they very nicely changed the name.

[3] There are 12 forks of the project and counting.