License: Other
This documentation is outdated.
Up-to-date documentation is reflected on the Exercism site at https://exercism.org/docs. The repository for those docs can be found in https://github.com/exercism/docs
Other Exercism repositories use 'good first patch' label for easily actionable items.
Add that label here so they can be found using a search query over all of Exercism.
As documented here: https://github.com/exercism/exercism.io/blob/master/CONTRIBUTING.md#good-first-patch
These are currently documented in
https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#updating-an-exercise-test-suite
They should be moved into the https://github.com/exercism/docs/tree/master/you-can-help directory in this repository. A good name would be update-exercise-test-suites.md
That will take two pull requests. One in this repository to add the new file, and one in the https://github.com/exercism/x-common repository to delete the copy that was moved from the CONTRIBUTING.md file.
A search for "core" in this repository has a few hints, mainly https://github.com/exercism/docs/blob/master/about/conception/progression.md#meaningful-and-flexible-linear-progression-in-exercism
A very important portion of that text seems to be "For a student learning a completely new programming language, completing the 10-20 core exercises would give students confidence that they've touched on the full range of key concepts" - this statement gives an overarching purpose that should drive the design of the track core.
I now have what I came for, so I'm going to close this issue immediately on filing. If you think it could be more prominently documented elsewhere and/or expanded on, you're free to discuss that.
When I'm mentoring I often want to write some code in a block, and need to mash space to add indentation.
There are tools to facilitate this
http://julianlam.github.io/tabIndent.js/
http://jakiestfu.github.io/Behave.js/
If I integrated something like that, would that be an appreciated pull request?
These are currently documented in
https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#exercise-versioning
They should be moved into the https://github.com/exercism/docs/tree/master/maintaining-a-track directory in this repository.
That will take two pull requests. One in this repository to add the new file, and one in the https://github.com/exercism/x-common repository to delete the copy that was moved from the CONTRIBUTING.md file.
This is not documented anywhere that I can find.
UPDATE: we settled on choosing the Creative Commons Attribution 4.0 International License:
http://creativecommons.org/licenses/by/4.0/legalcode
original issue:
Since the documentation is all text-based, I think it would make sense to have a creative commons license.
I don't know which one.
These are currently documented in
https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#track-level-linting-with-configlet
They should be moved into the https://github.com/exercism/docs/tree/master/maintaining-a-track directory in this repository.
That will take two pull requests. One in this repository to add the new file, and one in the https://github.com/exercism/x-common repository to delete the copy that was moved from the CONTRIBUTING.md file.
UPDATE: The discussion about how to resolve this was reopened—this issue is on hold until the linked discussion is resolved.
There's a very interesting discussion in exercism/discussions#2 discussing the problems around confusing exercise READMEs that don't always match the implementation of the exercise.
In particular, this occurs when we've discovered an inconsistency or ambiguity in a README, and then updated the README to clarify. Now we have a problem: some tracks chose to interpret the problem specification in one way, others in another. Now we have a README that clearly says one thing, and some implementations clearly do something else.
Updating all the implementations so that they match the specification can be a long and drawn-out process, because many people are involved, and some tracks don't have maintainers.
The discussion linked to above contains a great exploration of the problems and trade-offs, and also suggests a very practical solution.
This discussion should be boiled down to a short explanation of the problem, along with documentation about the process we should follow going forward.
This will likely link to the documentation about bulk issue creation, exercism/docs#10
https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md#configuring-the-exercise has slug, difficulty, topics. Should the example include all things in exercism/meta#16 ? Should it instead incorporate exercism/meta#16 by reference? Should something else happen?
If not, we run the risk that someone following the document will only include the three fields and configlet will not accept.
Granted, maybe that won't happen if they look at adjacent exercises and use them as examples, but even in that case it's still not clear the meaning of the UUID or how to get one.
This is the documentation that we have. We need to:
This is in the docs/ directory (https://github.com/exercism/exercism.io/tree/master/docs)
docs/
├── filing-a-bug-report.md
├── fixing-exercise-readmes.md
├── flipper-feature-flags.md
├── getting-involved-in-a-track.md
├── img/*
├── improving-consistency-across-tracks.md
├── inviting-new-maintainers.md
├── maintaining-a-track.md
├── overview-architecture.md
├── overview-of-exercism.md
├── porting-an-exercise.md
├── reviewing-a-pull-request.md
├── roadmap.md
├── setting-up-local-development.md
├── the-contribution-workflow.md
├── the-exercism-way.md
├── triaging-issues-in-a-track.md
└── writing-track-documentation.md
We also have a CONTRIBUTING file in exercism/exercism.io which has a lot of project-wide content.
This is the table of contents of the CONTRIBUTING file (https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md).
masterThese are currently documented in https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#pull-request-guidelines
They should be moved into the https://github.com/exercism/docs/tree/master/contributing-to-language-tracks directory in this repository.
That will take two pull requests. One in this repository to add the new file, and one in the https://github.com/exercism/x-common repository to delete the copy that was moved from the CONTRIBUTING.md file.
We have a section in the x-common contributing guide, called "Git Basics":
https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#git-basics
This entire section should be added to the contributing-to-language-tracks directory, in a file called git-basics.md.
add file: /language-tracks/documentation/for-contributors.md
Talk about:
Only the newsletter has this: http://tinyletter.com/exercism/letters/what-exercism-is-and-isn-t
... we need to add it somewhere, but not sure where.
I think it probably needs its own file, probably within the about/ directory. Maybe call it in-scope-out-of-scope.md
The last sentence is not complete in first-exercise.md.
add file: language-tracks/exercises/metadata.md
Some of this can be moved out of the ./language-tracks/exercises/anatomy/readmes.md file, and maybe also ./maintaining-a-track/regenerating-exercise-readmes.md
We currently have some documentation about creating a completely new exercise in https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#implementing-a-completely-new-exercise
We should extract this to a separate document in this repository, probably in the https://github.com/exercism/docs/tree/master/contributing-to-language-tracks directory, and flesh it out so that it reads as a consistent, complete document.
Then delete the contents from the x-common contributing guide.
This page: http://www.exercism.io/languages/fsharp/resources
Currently links to fpchat.com. However, that is no longer correct for the FP slack workspace. The new link is: https://fpchat-invite.herokuapp.com/
add directory language-tracks/tooling/
Can contain a README with an overview, link to the configlet documentation, talk about blazon, probot/stale, and other new bots as we write them.
In this issue, we discuss how to decide when to add topics to an exercise. Discussion seems to favour adding only topics that are essential/required for an exercise. To close this issue, all that would be left to do is to document this.
Original issue text:
It is possible to see that the current https://github.com/exercism/docs/blob/master/language-tracks/configuration/exercises.md#topics tells us
We show the topics for an exercise on the website. This lets people optimize the learning experience to their own interests—skipping topics that they are not interested in, or that they already know a lot about, and doing deeper dives into topics that they're curious about.
Recently in exercism/rust#558 (comment) I had questoins about when it is appropriate to add a topic.
Should a topic be put if it is possible that a solution might use it? Or should it only be put if a solution must use it (perhaps because the tests require it), etc.? Or are we supposed to exercise judgment and include a topic if we think any reasonable solution would use it? But what constitutes reasonable? etc.
I have now understood that the stated goal of topics is to allow a student to optimise the learning experience, though now I am pulled in both directions. Let's take the specific question of "should regular_expressions be added as a topic to pig-latin" to illustrate.
Having said those two things, I think it's a questoin of whether we try to optimise for one of those two cases... or something else, since those are not the only choices. So, what is the reasoning you choose to use when deciding topics?
(I understood from exercism/discussions#167 that topics are hard, though a large part of the discussion there was whether to have consistency between the different tracks, whereas I'm having trouble even deciding what to do for any one track, never mind multiple!)
Should we reference or intermix parts of this document (which I love) ?
readingSmalltalk.pdf
For the longest time, if anyone emailed me or tweeted at me and said "hey, could we have a track for the X programming language?" I'd go ahead and make it.
The problem with this was that often the person wasn't offering to implement and maintain a new track, they were just wishing out loud that it existed.
So we've ended up with a bunch of tracks that are kind of in the works—maybe—but probably not really, but we don't actually know. They might have one or two exercises, but they've not actually gone anywhere. They're not live on the site.
A few months ago I created a new repository, https://github.com/exercism/request-new-language-track, and the process is now to open a new issue in that repository. There's an issue template that asks some questions, and then we bootstrap a new repository and generate some starter issues. One of the starter issues is a "launch checklist", which guides the new maintainer through the process of implementing and launching the track.
This needs to be documented and added to the maintaining-a-track directory in this repository.
The documentation for this should give a high level overview of what to expect throughout the process, without duplicating the nitty gritty details (which can be left in the launch checklist).
The documentation about starting a new track in the problem-specifications contributing guide is not up to date, so that would need to be deleted.
So this issue has two tasks:
Since this is basically undocumented, don't be afraid to open a pull request with your best guess at a starting point. We'll be able to go back and forth from there—a lot of this is finding a way to force my brain to dump out the information that is there!
Per the discussion in exercism/discussions#128 we
will be installing the probot/stale integration on the Exercism organization on
April 10th, 2017.
By default, probot will comment on issues that are older than 60 days, warning
that they are stale. If there is no movement in 7 days, the bot will close the issue.
By default, anything with the labels security or pinned will not be closed by
probot.
If you wish to override these settings, create a .github/stale.yml file as described
in https://github.com/probot/stale#usage, and make sure that it is merged
before April 10th.
If the defaults are fine for this repository, then there is nothing further to do.
You may close this issue.
In instruction at https://github.com/exercism/request-new-language-track ("How to bootstrap a new track" -> "One-time setup"):
Install hub.
Clone the request-new-language-track repository.
Clone the tools repository
"Tools" it is link to https://github.com/exercism/tools
But this repo does not exist.
Or it is private repo.
*@cmccandless: Edited to restore original issue description for record keeping.
Came across this while changing the config to configlet 3.8.0 in exercism/javascript#527
The config spec says:
All optional exercises should be unlocked by one of the core exercises.
This made me think that all optionals should have this property - later found out that tracks have kept it null at many places. eg. ruby config. Also the latest version of configlet allows having null values.
Should unlocked-by be a required property? If not can we mention so in the spec?
In line with our new org-wide policy, the master branch of this repo will be renamed to main. All open PRs will be automatically repointed.
GitHub will show you a notification about this when you look at this repo after renaming:
In case it doesn't, this is the command it suggests:
git branch -m master main
git fetch origin
git branch -u origin/main main
You may like to update the primary branch on your forks too, which you can do under Settings->Branches and clicking the pencil icon on the right-hand-side under Default Branch:
We will post a comment below when this is done. We expect it to happen within the next 12 hours.
There are 6 subdirectories of this repository.
But what is the difference between all these?:
What seems to be covered in each one appears fairly arbitrary to me, and the directory names appear to overlap a lot.
contributing-to-language-tracks, language-tracks, maintaining-a-track (How are these different? where'd "language" go?)
contributing-to-language-tracks, contributing (to things that aren't language tracks?, what about problem-specifications that the language tracks rely on? or the other areas like the website and configlet and trackler/api where should they be documented?)
you-can-help how is "helping" different to "contributing"?
Hi. I was thinking about suggesting an exercise based on the n-queens problem:
Place n queens on an n by n chessboard such that no queen threatens another.
However the 'make up new exercises' instructions assume that a problem will have a unique solution for every input. In particular, it asks for "a set of sample test inputs and outputs that make up a reasonable test suite".
The n-queen problem has multiple solutions (4426165368 for n=8). Each is equally valid. You can't choose a particular solution for an n=8 test case.
You could constrain the n-queens problem to have a unique solution by demanding the lexicographically-minimum solution, but this would require people "to follow one very specific way to solve the problem", which makes for a less interesting exercise.
Has this been discussed before?
I could imagine a test suite for an unconstrained n-queens exercise, but it would need to do property-based testing rather than example-based testing.
Other interesting problems with multiple solutions:
I like these kind of problems, because they permit more freedom and creativity in their solution.
We often want to do one of to things:
For the second there are several scenarios:
We have some documentation about this in https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/improving-consistency-across-tracks.md
We should have a single document about submitting multiple issues, and then link from it where we mention blazon.
I couldn't find a document that talks about how we think about the exercise test suites.
There's a little bit in here: https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/improving-consistency-across-tracks.md but I think it would be great to have a top-level philosophy document that other documentation could refer to.
@parkerl @jtigger @IanWhitney @petertseng @kotp @ErikSchierboom you all immediately come to mind as maintainers who care about this, and have a good understanding of this.
Would you suggest some bullet points of what should be included in such a doc?
TODO
CHECKLIST and the TRAVIS filesThese are currently documented in https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#anatomy-of-an-exercise
They should be moved into the https://github.com/exercism/docs/tree/master/maintaining-a-track directory in this repository.
That will take two pull requests. One in this repository to add the new file, and one in the https://github.com/exercism/x-common repository to delete the copy that was moved from the CONTRIBUTING.md file.
The README.md file under maintaining-a-track points to the exercism/discussions repo which has been archived.
The config.json file has a number of options, and is kind of sort of referenced and halfway explained in a number of different places:
We should create a language-tracks/configuration/README.md that documents the config.json file fully.
Remember to include the test_pattern, ignore_pattern, and solution_pattern keys.
There's also a gitter key.
As of exercism/meta#3 there is no longer an "ignore" key in the config.json.
The contribution guides lay out details for getting started and submitting PRs. But it doesn't cover things like PR merging strategies and issue resolution processes on GitHub. So I am creating this thread to begin hashing out details for such topics.
This thread is a continuation of a short discussion that started on exercism/cli#432 (comment)
We have:
https://github.com/exercism/problem-specifications/blob/master/CONTRIBUTING.md
and
https://github.com/exercism/docs/tree/master/contributing-to-language-tracks
which cover similar ground but were obviously written separately. Is one of these considering more definitive than the other moving forward? Which resource should tracks be pointing interested newcomers to?
There are bunch of terms that get used in the code of x-api/trackler/exercism.io/configlet etc.
Such as: Track, Exercise, Slug, ID, Problem, Specification, Implementation
It would be good to have a place where we could canonically list the definitions, and their intended usage.
The order of exercises within the exercises array of config.json is significant.
The documentation: https://github.com/exercism/docs/blob/master/language-tracks/configuration/exercises.md
should be updated to mention this.
The implementing first exercise doc has an unfinished statement at the end.
Once
lintis happy, runconfiglet fmt ., which
Trying to follow the instruction given below, but not able to find the said location of contirbution in the sidebar.
https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md#finding-an-exercise-to-port
Please the update the doc if required or someone can help me understand this.
There are things that we do to keep the lights on. Is this the place to document those things too?
There is a slightly outdated section in the x-common contributing document about track anatomy: https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#track-anatomy
A great first step would be to move this into this repository. It should go into /language-tracks/README.md
A nice plus would be to delete the bulk of the explanation about the docs/ directory, and instead link to the https://github.com/exercism/docs/blob/master/maintaining-a-track/writing-documentation.md document.
Then open a PR that delete's the section from the problem-specifications contributing document.
Note: we'll need to add a section about the .meta/ directory.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.