Java: Make it more clear which exercises can't be implemented for Java

[FridaTveit]

There are a few exercises that can't be implemented for Java: leap, grains and say. See issue #3 for an explanation of why.

The build will fail if someone tries to open a PR to add them, but apart from that it's not very obvious that they can't be added. Therefore we risk someone implementing them before realising they can't be added. There's already been several PRs openened and closed for leap.

To avoid that it would be good if we could make it more obvious that these exercises shouldn't be added for this track. Maybe adding a sentence or two to the contributing guide or something would help? What do you think @exercism/java? 🙂

[Smarticles101]

I agree, it would be nice to add them to the contributing guide. Then we would just have to worry about the people who don't read the contributing guide. Maybe a pull request template would be good for getting information across.

[lemoncurry]

I would propose to reference maybe an open issue that includes a list of all exercises that are not implemented yet in the contributing guide.
This list could also include a section for those exercises that are excluded from the track. Right now there is already a link that leads to a general page for contributing -> https://exercism.io/contribute.

[FridaTveit]

We did have a link to an exercism.io page with a list of exercises not implemented yet on the Java track, but it doesn't appear to exist on exercism.io anymore 🙁 I guess we could create and maintain our own list?

[junming403]

Hi, I want to contribute to this repo. I am considering adding some algorithm questions. Should I propose the topic for approvement first? Thank you

[FridaTveit]

That's great that you want to contribute @junming403! 🙂 Do you mean you want to add new exercises? In which case that needs to be done in the problem specifications repo. We only implement the exercises that are specified in that repo 🙂 Does that make sense?

If there are any exercises in the problem specifications repo that aren't implemented on this track then you can also open a PR in this repo to implement one of them. See our contributing guide for more details on how to add a new exercise 🙂

[junming403]

Hi, I see, is there a list of missing problems I can try to contribute to?

[FridaTveit]

There used to be but I don't think there is anymore unfortunately 🙁 So I think the easiest thing to do at the moment is just to see if there are any exercises in the problem specifications repo that aren't in our list of exercises in this repo. You can then try to port over any of those exercises (apart from leap, grains and say as explained in this issue).

You can also update the tests for any of the exercises. To do that you can run a script to check which tests need updating 🙂

And you can suggest new exercises or improvements to the current exercises in the problem specifications repo 🙂

[SleeplessByte]

FWIW:

These exercises were inspired by Java Ranch and are not allowed to be implemented.

This doesn't explain why it's not allowed to be implemented. You need to know what Java Ranch is, and infer that it's a licensing issue.

[jmrunkle]

I had a thought about this - perhaps we could have a directory in the repo for the exercises that are not allowed to be implemented that just has a markdown file explaining why the exercise cannot be implemented. Perhaps called DO_NOT_IMPLEMENT.md. Anyone who goes to put the forbidden exercises would have to ignore that pretty obvious file in order to try to add those exercises. Does anyone like that idea? Would it break the code that checks to see if anyone tries to add a PR for these exercises (and if so, perhaps we could add that exception)?

[jmrunkle]

To make that more clear, each exercise that cannot be implemented would have its own directory like the other exercises. For example: exercises/leap/DO_NOT_IMPLEMENT.md

And the contents of DO_NOT_IMPLEMENT.md would explain why.

[jmrunkle]

Created PR #1711 as a better demonstration of the idea...

[lemoncurry]

@jmrunkle Thank you for tackling this issue.

There are only three exercises that are affected and this list is not expected to change.
I was just wondering if there might be much simpler solutions that might not break the structure of the language tracks and that might not require a change in configlet.

For example (listing of other proposals already mentioned in this issue):

• How about just pointing out the respective exercises in the CONTRIBUTING file?
• Or we could pin an issue that lines out those exercises that should not be touched.
• ...

What do you think about these simpler solutions?

BTW: All exercises that should not be implemented are listed under "foregone" in the config.json, but this obviously is not enough to point to those exercises for new contributors.

[SleeplessByte]

Actually, I think creating a DO_NOT_IMPLEMENT.toml or similar file in the root, and then setting up the CI to fail if they are, is sufficient enough :)

[jmrunkle]

@lemoncurry Thanks for the additional suggestion.

There are only three exercises that are affected and this list is not expected to change.

While that may be the case, we do not know for certain that these 3 will be the only affected exercises - nor are we the only track that may have to contend with this issue (I assume other tracks also may have reasons that they cannot implement a certain set of exercises).

How about just pointing out the respective exercises in the CONTRIBUTING file?
Or we could pin an issue that lines out those exercises that should not be touched.

I'm not saying that we cannot do any of the other proposals - just that this would be more effective. Every other proposal that I have seen has the downside that a contributor may not notice that the exercise should not be implemented until they have already gone and implemented it. The presence of a single markdown file in an exercise directory that they would want to implement is a much stronger indicator of the fact that they should not implement that exercise and it shows up just-in-time rather than requiring them to read some external source (either the CONTRIBUTING file or a specific issue). Similar to the fact that the "foregone" list in the config is insufficient for this purpose.

Also, the modifications to the configlet were not very complicated and I already have a pull request for those changes (https://github.com/exercism/configlet/pull/163).

[SleeplessByte]

I assume other tracks also may have reasons that they cannot implement a certain set of exercises

This assumption is correct.

[lemoncurry]

@lemoncurry Thanks for the additional suggestion.

There are only three exercises that are affected and this list is not expected to change.

While that may be the case, we do not know for certain that these 3 will be the only affected exercises - nor are we the only track that may have to contend with this issue (I assume other tracks also may have reasons that they cannot implement a certain set of exercises).

Yes, that is true, of course. But the list hasn't changed in a long time and I would hesitate to say a global change of the track structure is justified.

How about just pointing out the respective exercises in the CONTRIBUTING file?
Or we could pin an issue that lines out those exercises that should not be touched.

I'm not saying that we cannot do any of the other proposals - just that this would be more effective. Every other proposal that I have seen has the downside that a contributor may not notice that the exercise should not be implemented until they have already gone and implemented it. The presence of a single markdown file in an exercise directory that they would want to implement is a much stronger indicator of the fact that they should not implement that exercise and it shows up just-in-time rather than requiring them to read some external source (either the CONTRIBUTING file or a specific issue). Similar to the fact that the "foregone" list in the config is insufficient for this purpose.

Thank you for explaining why you thought a global change in the track structure might be needed. I see your point that the CONTRIBUTING file or the spec. issue about exercises that should not be implemented might be missed.

Also, the modifications to the configlet were not very complicated and I already have a pull request for those changes (exercism/configlet#163).

Although it might not be complicated, do you know if any other repositories, such as eg for the website, or our own scripts for maintaining this track, might be affected by this change in the track structure?
Does your proposal then affect all language tracks so that all then need to keep the same structure for those exercises?

I assume other tracks also may have reasons that they cannot implement a certain set of exercises

This assumption is correct.

Maybe the discussion should be open for all tracks and transferred to exercism/exercism. It would be great to have the opportunity to hear from other track maintainers and their experiences with this issue. It might also be possible that there already exist simple solutions in some language tracks that we could use in the Java track.

[jmrunkle]

As you well know, there is no way I could possibly know if there might be a script / tool out there somewhere that has a problem with this sort of structure. If we find such a tool that has a problem I would probably ask them to ignore directories for exercises that are foregone in the config file (which should be pretty easy to parse from the config file since that is what it was built for).

I'm fine with opening up the discussion on exercism/exercism. I'm a little worried that just opening an issue there will not sufficiently increase the visibility. Perhaps we need to voice it on the maintainers slack channel so that others will see it clearly. At the very least that issue should also link back here so that things which were already discussed can be part of that conversation as well.

[FridaTveit]

@jmrunkle it is possible that you could know of a script or tool that we use for exercism that could have a problem with this structure, so @lemoncurry asked a valid question. And even if you don't know of one, it is still a valid concern that we don't know what the full consequences could be of making this change.

I think it's definitely a good idea to discuss this with other maintainers as @lemoncurry suggested 🙂

[jmrunkle]

@jmrunkle it is possible that you could know of a script or tool that we use for exercism that could have a problem with this structure, so @lemoncurry asked a valid question. And even if you don't know of one, it is still a valid concern that we don't know what the full consequences could be of making this change.

OK fair enough, I could know that a tool I knew of did have a problem with this, but the effect of the question means that I would have to know that there exists no tool that has this problem. I could not reasonably be expected to know that there is no such tool in use that would have a problem with this so I answered for that rather than the more limited (and less useful) knowledge of only tools that I am aware of. The issue itself is nearly intractable and makes any changes whatsoever to the configlet suffer from the same issue (any change to the configlet affects many other repos that have tools that may not support the things that the configlet might allow).

Regarding asking this question to other maintainers... do I just pose a new question on exercism/exercism then (and reference this issue)? I can also link to it from the slack channel so that other maintainers would see it as well.

[FridaTveit]

Well, if someone asks if you know of an example of something, you can just say no. You don't have to prove that an example doesn't exist 🙂

But we're getting carried away by a detail which doesn't really matter. The point is that we volunteer our time here because we want to make sure Exercism is a good place to learn and contribute. So please don't assume the worst from our comments. We're not trying to be difficult, we just want to make sure we find the best solution for the people who use and contribute to Exercism 🙂

So yes, I think opening an issue in exercism/exercism asking if any other tracks have this issue and how they've solved it. You can also propose your solution and see if people think that's a good idea that they think would be useful on their tracks. And yes, linking to it from the slack channel is probably also a good idea 🙂

[jmrunkle]

Sounds good. My initial reply about the possibility of a tool that would have a problem may have sounded too harsh, but it was not meant in an unkind spirit. I appreciate everyone who volunteers their time (as I do as well) to think about and work on these issues.

I'll post an issue in exercism/exercism and link it back over here as well as linking it from the slack group.

[FridaTveit]

Sounds great 🙂Thanks for trying to find a solution to this issue! 🙂

[jmrunkle]

As you all might guess from the reference - created https://github.com/exercism/exercism/issues/4932

[lemoncurry]

Thank you @jmrunkle and @FridaTveit .

[sshine]

I've provided a summary of exercism/exercism#4932 in that thread.

What is the frequency between requests to implement one of these exercises?

Here are some actionable items to move forward:

• Add a list of do-not-implement exercises to CONTRIBUTING.md#adding-a-new-exercise, e.g. by linking to the track maintenance dashboard. I'm thinking that if this list is the first new contributors scan through, they won't accidentally implement a do-not-implement exercise.

• Remove these exercises from https://tracks.exercism.io/java/master/unimplemented by adding their slug to the foregone key in config.json.

• Consider revising your reasons for not implementing them, since @kytrinyx said this:

  As far as I know, nobody is suable, as long as we provide attribution, and we write our own descriptions. [...] I think we are fine to implement them if we want to, I was just being extra careful early on

• If you think people won't notice a do-not-implement list before submitting a PR, then perhaps this is an indicator that the contributing guide isn't being read. If that is the case, consider shortening it so that the important parts are written first and the details are located elsewhere.

  I've recently started simplifying README.md on the Haskell track (which contains our contributing guide), but I'm only half done. Perhaps you can see the difference between the sections before and after the header "Repository structure and conventions".

Edit: Changed the sections around a bit.

[yawpitch]

As the justification for _not_ implementing leap, grains, and say in Java has has been mooted, and as all three exercises were removed from foregone in #1713, and since both leap and grains have already been implemented, with say about to be in #1769, I'd say the _primary_ action item on this Issue is to close it.

[SleeplessByte]

I agree. It's not longer an issue. It can be revisited if it ever _becomes_ an issue again. I would _suggest_ if an exercise is foregone, for whatever reason, to, perhaps, create a file FOREGONE.md at the root and document it there, if necessary -- OR you enforce it to be in the git message, which will make it surface on git blame or history.

@ErikSchierboom just tagging you: do you document somewhere _why_ certain exercises are foregone in 'your' tracks?

[ErikSchierboom]

@SleeplessByte Actually I didn't, although I should have!

[yawpitch]

Since exercism/exercism#4932 has been closed, this probably should be as well.

[kytrinyx]

Thanks, all! I'm closing this, as suggested.