Launch tracking
Closed this issue · 148 comments
This issue helps keep track of the tasks you're working on towards launching this track.
The next steps are:
- Join our community
- Select programming language variant (if applicable)
- Select testing framework
- Add the first exercise
- Add initial exercises
- Setup Continuous Integration
- Prepare for launch
- Find Maintainers
- Launch!
- Implement tooling
- Prepare for open source contributions from strangers
Once you've finished a task, you can check them in this list.
Questions
Please ask if you have any questions or if anything is confusing!
So, where do I learn how to make exercises in general? Do I need to download exercism to my machine?
Hey @TriAttack238 I think this link might help:
https://exercism.org/docs/building/tracks/new/add-first-exercise
Thanks!
Wait, can you create and run a function in COBOL without having to put it inside of the procedure division of the main program?
In any case, I’ll be right on these initial exercises when I have the time.
AFAIK that's not possible with COBOL, you need at least the ID division and the procedure division.
Oh man that’s going to be one big stub.
I think we can make it work, well find a way. It is different from anything else so it's really worth it to teach this, even if it's just to give a different perspective.
Let’s just warn the students not to touch any capitalized words at the start.
One way would be to make a static identification division that's used for every exercise.
And the code that the user writes would be concatenated to it.
Or we teach the students about the divisions and that they're necessary.
And warn them about removing it, like you said.
It's also worth it to note that modern COBOL doesn't require capitalized keywords, so warning the students about those might not work.
Another issue would be which format do we teach to the students on this track?
COBOL has fixed format and free format.
Fixed has very specific rules of where certain things should go, like line numbers, comments, divisions and sections.
Free is more like modern languages, where you don't need to explicitly write line numbers and it's more relaxed on indentation rules.
Speaking of that I should also work on a COBOL highlightjs package.
It's also worth it to note that modern COBOL doesn't require capitalized keywords, so warning the students about those might not work.
But capitalizing keywords is still in best practices. For example in the Python track constants are taught with capitalized names, even though Python doesn’t actually have constants.
That's true, but I'm afraid of it being best pratice in COBOL due to legacy systems being written in all uppercase rather than it being better to write that way.
Python uses uppercase for constants to differentiate between normal variables, that makes it easier to find constants.
We could teach that COBOL is case insensitive and explain why they would want to write it in uppercase, to give the students an option on how to write it.
Another issue would be which format do we teach to the students on this track?
COBOL has fixed format and free format.
Fixed has very specific rules of where certain things should go, like line numbers, comments, divisions and sections.
Free is more like modern languages, where you don't need to explicitly write line numbers and it's more relaxed on indentation rules.
I’m aware of the differences, but it’s a tough question. I personally prefer free, and it’s in the standard, but it would make older code harder to understand if it’s learned first. However, unit tests technically only care about the result, not how, so it might be possible to talk about both.
However, unit tests technically only care about the result, not how, so it might be possible to talk about both.
Yea we should talk about both. If they encounter COBOL in a real world situation it's possible it'll still use fixed format.
Something else to iron out is if we’re making this a learning mode course we need a track of concepts that creates a smooth learning curve and makes sense.
Maybe we could teach according to the order of the divisions like this?
identification division...
environment division...
data division...
and then procedure division...
Not sure if that would make sense for a new student though.
No, I don’t think so, that would be like having a driving class and starting by talking about the history of roads. The course should get the students to start doing things as soon as possible. We’re trying to avoid the mistakes of the book here.
That's true. So do we start with the procedure division and explain things as they are needed along the way?
identification division.
program-id. hello.
procedure division.
display "Hello, World!".
stop run.This is how would it would look like if we start with free format for the hello world.
Not quite that broad. If you look at the syllabi of the learning languages, they focus on specific features: strings, floating point numbers, lists, classes. So we should think on a more granular level:
-Basics(variable declaration, the MOV operation
-numbers(fixed point computing, mathematical operations)
-floating point numbers
-string handling(https://www.tutorialspoint.com/cobol/cobol_string_handling.htm)
-edited pictures
-group data items
-tables(arrays)
And the harder ones:
-sequential file processing(record buffer, control breaks)
-objects
I don’t think it’s necessary to get into stuff like pointers or indexed records, but they would be advanced concepts.
That sounds good, so we should start with the basics first?
Yes
identification division.
program-id. exercism-variables.
data division.
working-storage section.
01 ws-var pic x(13) value "Hello, World!".
procedure division.
display ws-var.
stop run.This is how a hello world would look with variables.
But it would be in a function the returns the literal right? That’s what the page says.
It would be too confusing for students to start with user defined functions. They have their own divisions as well.
Then just have a stub with all that stuff in the first exercise
If you look at the website, every track starts with a complete function returning “Goodbye, Mars!” the student changes to “Hello, World!”. So, we just do that in COBOL
every track starts with a complete function returning
Issue is that COBOL user defined functions would be too complex for starting students who don't understand COBOL. We can start with the basics first, COBOL procedure division can be considered a C-like Main function.
If you use procedure division returning ws-variable. it returns a value, but that's not needed if we're just displaying "Hello, World!".
But we don’t need to teach the syntax for the first one, the first exercise is changing the returned literal and that’s it. I think the return part is crucial for unit testing. Just log onto a track and check.
But yeah if we can trim it down that still works.
Hmmmm we can try, I'll see if I can make a working user defined function program. I'm afraid of scaring people when they see it hahah.
Excited to see this underway. Thanks everyone!
Some cc's:
- @ErikSchierboom for helping y'all understand about how to get everything running happily in Exercism's env
- @joshgoebel for HighlightJS
- @axtens as he's been planning this for a while and should be co-leading on it 🙂
I've also enabled Pull Requests as a requirement in this repo as there's multiple people working on it..
Also, it'd be great if you'd organise a chat with @jonathandmiddleton to get to know your way around Exercism's community of maintainers.
But yeah if we can trim it down that still works.
IDENTIFICATION DIVISION.
FUNCTION-ID. EXERCISMFUN.
DATA DIVISION.
LINKAGE SECTION.
01 LS-VAL PIC 9(1) VALUE 1.
PROCEDURE DIVISION RETURNING LS-VAL.
DISPLAY "Hello, World!".
GOBACK.
END FUNCTION EXERCISMFUN.
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLO.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY. FUNCTION EXERCISMFUN.
PROCEDURE DIVISION.
DISPLAY FUNCTION EXERCISMFUN()
STOP RUN.This is an example of a used defined function in COBOL, I'm sure it could be written in a better way, but documentation on this is really really bad at explaining how exactly it works. The function is the first thing there and it displays "Hello, World!" and returns 1. The second thing is for calling that user defined function.
I tested it with gnuCOBOL and it works.
This is another reason why we really need to build this Exercism track, COBOL documentation is not really that good right now.
Hey @iHiD, thanks for joining us here.
I'll certainly ask @joshgoebel about how HighlightJS works, currently there doesn't seem to be a package for COBOL Highlighting for HLJS. Maybe he could help us with that?
I'm in UTC+8 and still at breakfast. I've been praying for a time such as this. I will get back to you all later in the day.
Hey @axtens, thanks for joining us.
Time to make some good and easy to understand COBOL documentation? Can't wait to see this working on Exercism.
I mean, if COBOL is like English, then we just need to make an English textbook. That’s not too hard, right?
Might not be that simple, it would be like making a complete English textbook when all current English textbooks are not complete or don't explain things clearly.
That’s when we consult the giant book(the standard).
Oh yeah, is there a way to have "debrief" documents? COBOL has a lot of aspects where you can follow the book and do a thing but not understand at all what happened. For example, the "hello world" assignment will have quite a bit of writing that a student may want an explanation on, like the whole concept of divisions and sections.
In any case, I've started to learn markdown in full.
Edit: Alright, got the basics down.
I'm working on the highlightjs package. This might take a while.
But this made me realize how many keywords are actually non-standard. A lot of tutorials and videos use keywords that are not present in the standard.
Interesting. Tomorrow I'll try to figure out the first test in my own branch. What testing framework are we using again?
@TriAttack238 I think it's this one:
https://github.com/openmainframeproject/cobol-check
Hey @axtens, is this the testing framework that we'll be using?
That's the one. If you join #maintaining-cobol in Exercism' s Slack you can discuss that decision with Sven
I've emailed you an invitation
@KTSnowy It should be reasonably easy to create a new 3rd party highlighting module for Cobol. Minimally you could start with just a huge list of keywords. (which it looks like you already have) Happy to help with any specific questions.
See our docs:
- https://github.com/highlightjs/highlight.js/blob/main/extra/3RD_PARTY_QUICK_START.md
- https://highlightjs.readthedocs.io/en/latest/language-guide.html
Also perhaps just browse thru the built-in languages till you find one of the simpler ones... seeing some existing languages can give you an idea of what you're looking to accomplish.
Is Cobol the language still undergoing many changes today or is it mostly static?
Is Cobol the language still undergoing many changes today or is it mostly static?
It's still receiving updates, the latest 202x standard draft is in the voting phase.
https://github.com/otterkit/highlightjs-cobol
I made this, not sure if it's working though. I'll test it later.
I used the other highlightjs repos as a template for the readme and contributing files.
Highlightjs-cobol is mostly working, just need a few tweaks.
@KTSnowy You can do operators, but not how you had it before... every item in contains has to be a full mode... so a very simple rule would just have a scope and match:
contains: [
{ scope: "operator", match: /\+/ } ]
So you'd make a bunch of separate rules - you could also do this programmatically - it's just JS, but most commonly you'd probably do this with the regex helpers:
OPERATORS = [ /*array of operators */ ]
// later
contains: [
{ scope: "operator", match: regex.either(...OPERATORS) } ]Depending on your operators they may need special escaping... I'd have to double check. regex.either is just a nice wrapper that builds a (x|y|x) regex.
If your keywords are going to include - you need to use keywords.$pattern and specify a regex that is able to match potential keywords... the default is like \w* or something, which doesn't include -.
Ok, I'm opening up a new branch. @KTSnowy, you already merged your Json changes, right?
@TriAttack238 we already did, the config.json should be working correctly now.
I'm now working on fixing the issues with the syntax highlighter.
Nice, I'll see if I can get this first test working or at least add some concepts.
For a given concept, when is about.md shown compared to introduction.md?
@joshgoebel I can't find a way to make operators work and I can't find any documentation on regex.either( )
But I did fix the keyword pattern, so that's working now.
Can I get permission to make a branch please?
Can I get permission to make a branch please?
We have to ask @kytrinyx I think. I don't have permission to add you.
@TriAttack238 I created a branch for you:
https://github.com/exercism/cobol/tree/triattack238-devbranch
See if you can work on this branch
Nope, still can't change the branch
Hey @kytrinyx @iHiD, could we add @TriAttack238 to the repo so that they can make changes to their branch?
Please?
@KTSnowy is it possible for @TriAttack238 to fork the branch, work from there, and push back using a PR? This could help in the intermediate.
That might not be a bad idea.
@SleeplessByte I think it could work.
I invited @TriAttack238 yesterday but the invite has not yet been accepted. But using forks as @SleeplessByte suggested is a good idea anyway.
Sorry, forgot that the app doesn't show certain notifications.
Alright, KT finished the first exercise so I'm going to check off the box.
Hey, should we have example code snippets in fixed or free format?
Hey, should we have example code snippets in fixed or free format?
I think we should mostly use free format, and talk about fixed format and it's rules separately.
This is because free format is more similar to how modern languages work, and fixed format has very strict rules that could be frustrating for students if they had to use it for most exercises.
Got it. I was wondering because your first exercise stub is in fixed format.
IIRC gnuCOBOL uses fixed format by default, so we might have to pass the -free command line option to it for most exercises.
I personally just include 'source FREE' in my programs, but that also works.
I was wondering because your first exercise stub is in fixed format.
The hello world example? It's using free format, but without the compiler directive.
Ah, I see now.
I used the -free command line option so that I don't have to write free format on every file.
Wait, KT, on your test stub the GOBACK keyword is before the return variable is initialized. So it doesn't activate immediately?
Also, should we teach students to add STOP RUN and/or STOPing the program? It's only useful when using open subprocedures, but it might be important as a best practice.
Alright, so at first that sounded a bit weird so I checked the hello-world example and it seems to have been changed from the one I uploaded yesterday.
And you're right, the one currently there doesn't do anything since the goback is the first clause in the procedure division. And it should be STOP RUN to return control back to the OS, goback is only for subprograms and user defined functions to return control to the calling program.
@TriAttack238, STOP RUN is used when you need to completely stop execution and return control back to the OS, GOBACK is when you want to stop execution of a subprogram or user defined function and return control to the calling program.
As I assumed, and GOBACK also returns the current value of the promised variable, right?
Alright, my branch now has its first full draft of the introduction. Feel free to check it out.
GOBACK doesn't return any values, to return a value you need to define it on the procedure division like this: procedure division returning $VARIABLE$.
This will return a value when exiting the program.
Ok, got it.
Hey @axtens, what happened with the previous hello world example? The current one is using fixed format and it immediately uses the goback statement.
I added support for number highlighting in version 0.2.12 of the highlightjs package
Here's a test example:
https://codepen.io/ktsnowy/pen/vYRXxov