Freecodecamp: Create single source of user stories and notes for back-end Node certification projects

[RandellDawson]

Internally, we had several discussions about the pros and cons of moving all the user stories for the back-end certification projects to a single location. The decision was to move all the user stories and notes for the back-end Node projects to learn.

Goals:

• Creates a single source for user stories and instructions to reside.
• Makes it easier to create translations of these projects’ instructions.
• Make them easier to maintain

Tasks:

1. Each user story will be a test text in the learn file. The user stories should be written from the second person perspective.
2. The description section of each learn file should be standardized to include a link to the demo project and to the boileplate (repl.it and github.com). Any supplemental information likes notes or examples would be incorporated in the bottom of description section. Here's how the markdown should look:

Build a full stack JavaScript app that is functionally similar to this: <a href='https://timestamp-microservice.freecodecamp.rocks/' target='_blank'>https://timestamp-microservice.freecodecamp.rocks/</a>. Working on this project will involve you writing your code using one of the following methods:

- Clone <a href='https://github.com/freeCodeCamp/boilerplate-project-timestamp/' target='_blank'>this GitHub repo</a> and complete your project locally.
- Use <a href='https://repl.it/github/freeCodeCamp/boilerplate-project-timestamp' target='_blank'>our repl.it starter project</a> to complete your project.
- Use a site builder of your choice to complete the project. Be sure to incorporate all the files from our GitHub repo.

When you are done, make sure a working demo of your project is hosted somewhere public. Then submit the URL to it in the `Solution Link` field. Optionally, also submit a link to your project's source code in the `GitHub Link` field.

1. Use the user stories with the most specificity. e.g. If the user stories are more specific on the README.md (boilerplate or demo-project) or index.html of demo project, use those on /learn for the test text.
2. Each boilerplate README.md file should only contain a project title that links to the the applicable learn page project. Any other text should be deleted. Example:

# [URL Shortener Microservice](https://www.freecodecamp.org/learn/apis-and-microservices/apis-and-microservices-projects/url-shortener-microservice)

1. Any user stories or instructions should be removed form the project code files (i.e. myApp.js or server.js.
2. Remove any user story information from a project’s landing page (i.e. index.html). The only thing that should remain would be example usage information. This applies to the demo projects and boilerplates.

Notes:

• The project demos are hosted in the demo-projects repo
• Please limit PR's on /learn to one project at a time
• PR's to boilerplates cannot be merged until changes on learn hit production.
• Once all changes have been deployed, the README.mds for each project in the demo-projects repo will be deleted.
• If you would like to work on one of the projects, please reply so we can add your name to the table below, to avoid duplicate work by other contributors.

| Certification Project|Demo Project | Boilerplates | /learn |
| :-- | :-- | :-- | :-- |
| Timestamp Microservice
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/24

|

• [x] Has user stories removed
• [x] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-timestamp/pull/43

|

• [x] Has user stories
• [ ] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39961

|
| Request Header Parser Microservice
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/25

|

• [x] Has user stories removed
• [x] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-headerparser/pull/12

|

• [x] Has user stories
• [x] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39964

|
| URL Shortener Microservice
- challenge file
- boilerplate
Assigned to: @Sky020 |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/21

|

• [x] Has user stories removed
• [x] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-urlshortener/pull/23

|

• [x] Has user stories
• [x] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39311

|
| Exercise Tracker
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/26

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-exercisetracker/pull/42

|

• [ ] Has user stories
• [ ] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39965

|
| File Metadata Microservice
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/27

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-filemetadata/pull/9

|

• [x] Has user stories
• [ ] In production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/40217

|
| Metric-Imperial Converter
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/28
• https://github.com/freeCodeCamp/demo-projects/pull/37

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-metricimpconverter/pull/12

|

• [ ] Has user stories
• [ ] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39615

|
| Issue Tracker
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/32
• https://github.com/freeCodeCamp/demo-projects/pull/34

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-issuetracker/pull/15

|

• [x] Has user stories
• [ ] In production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39627

|
| Personal Library
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/33
• https://github.com/freeCodeCamp/demo-projects/pull/39

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-library/pull/5

|

• [x] Has user stories
• [ ] In production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39642

|
| Sudoku Solver
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/22

|

• [x] Has user stories removed
• [x] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-sudoku-solver/pull/8

|

• [x] Has user stories
• [x] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39816

|
| American British Translator
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/23

|

• [x] Has user stories removed
• [x] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-american-british-english-translator/pull/6

|

• [x] Has user stories
• [x] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/39822

|
| Stock Price Checker
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/31

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-stockchecker/pull/13

|

• [ ] Has user stories
• [ ] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/40218

|
| Anonymous Message Board
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/30

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-messageboard/pull/9

|

• [ ] Has user stories
• [ ] On production
• https://github.com/freeCodeCamp/freeCodeCamp/pull/40219

|
| Secure Real Time Multiplayer Game
- challenge file
- boilerplate |

• [x] Has user stories removed
• [x] Is hosted on .rocks
• https://github.com/freeCodeCamp/demo-projects/pull/29

|

• [ ] Has user stories removed
• [ ] Readme has link to /learn
• https://github.com/freeCodeCamp/boilerplate-project-secure-real-time-multiplayer-game/pull/5

|

• [ ] Has user stories
• [ ] On production

|

[nhcarrigan]

For this one, I've got a couple of PRs open to add tests.

Would it be preferred to roll these changes into those PRs or open new separate PRs?

[RandellDawson]

Just keeping it as a discussion for a very short time in case anyone can point out any issues with making these changes.

@Sky020 @nhcarrigan @SaintPeter We are aware there are a few PRs you all are working on related to one or more of these projects. For now, just continue implementing your changes as you had planned, though I do suggest waiting until we open this issue up for PRs before creating any new PRs for the projects.

[SaintPeter]

Can you please clarify what you mean by "test text"? Is that the - text in the YAML? Meaning that the only place the user stories will be found is there?

There is a potential issue with that for some of the untestable user stories. Even with the changes I've proposed to the Sudoku Solver and American/British Translator, there are front-end specific user stories that we cannot test. Is the expectation that we have an "empty test" with that user story?

If I recall correctly, @nhcarrigan mentioned that there were similar issues on the "Anonymous Message Board" project.

[nhcarrigan]

Correct - I did have some tests I couldn't figure out.

Though if we end up rebuilding the projects to hit a backend API endpoint instead, that issue becomes moot.

[moT01]

Those are those tests the functional/unit tests, correct? If that's the case, I don't think we should get rid of them. So that leaves either moving them along side the rest of the tests (at the bottom of each challenge page) - or moving the non testable user stories to the instructions area of the challenge page. Pretty sure there's several out there now that just put the text at the bottom of the challenge pages as if there are tests. I think that, for now, we would be fine doing that and once we get everything moved over to learn, perhaps we can look into moving some user stories to the instructions area. Or trying to find a way to actually test some of them.

You mentioned on the other issue @SaintPeter,

Update the fCC tests to just check the /_api/get-tests end point and parse for passed on various tests.

Would this not work for those? Just check if they're all passing?

[SaintPeter]

Update the fCC tests to just check the /_api/get-tests end point and parse for passed on various tests.

Would this not work for those? Just check if they're all passing?

I suppose we could check for the specific test names and look for "passed" and at least one assertion. In conjunction with the actual testable endpoints, that does seem reasonable. I had been against using JUST the /_api/get_tests output, but using it for a smaller part would probably be ok.

We can add additional admonishments to the boilerplate 2_funcational_tests file against each test that is only checked via the _api. Something like:

// Do not change the name of this test

We would need to make sure they were not any of the function ______() tests, since those seem to invite modification.

[moT01]

I think for this issue then, those should just go down by the tests (bottom of challenge page) with the rest of them.

[RandellDawson]

We can add additional admonishments to the boilerplate 2_funcational_tests file against each test that is only checked via the _api. Something like:

// Do not change the name of this test

This was not discussed before, but we do not want to add comments to the boilerplate code. All instructions will need to be made in either the tests' text or in the description section as notes. Why? Because we are not translating the boilerplates. This should really be an additional bullet point in the Tasks above.

[Sky020]

@RandellDawson Sign me up for the URL Shortener project. I will keep track of the current PR against it, and work from there to implement these changes.

[moT01]

Note, I updated the text that should appear on /learn from this...

    > Build a full stack JavaScript app that is functionally similar to this: https://metric-imperial-converter-freecodecamp.rocks/.
    > 
    > Working on this project will involve you writing your code using one of the following methods:
    > 
    > - Clone this GitHub repo and work on your project locally.  After completing the project, host a live version of it somewhere and submit the url to it in the `Solution Link` field below.  Also, post the link to your GitHub repo in the `GitHub Link` field below.
    > 
    > - Use our repl.it starter project to complete your project.  After completing the project, submit the public url (the homepage of your app) in the `Solution Link` field.  Optionally, submit a link to a repository of your source code in the `GitHub Link` field.
    > 
    > - Use a site builder of your choice to complete the project.  Make sure to incorporate all the files shown in the GitHub repo.  When you are done, submit the URL to your publicly available site (to the homepage of your app) into `Solution Link` field below. Optionally, submit a link to a repository of your source code in the `GitHub Link` field.

To what is now in the issue. I thought it was more concise this way, but we can change it back if we don't like it.

[Sky020]

@moT01 I am wondering if we should not remove the mention of completing the projects locally?

This has to do with the cert projects, and their submissions should be publicly visible. So, either remove its mention in the list, or remove the

...using one of the following...

Being explicit about the need to host the project somewhere, once they are done.

[moT01]

It does say to submit a "working demo" - perhaps we could add "publicly visible working demo" ? Or is that not explicit enough.

[moT01]

number 6 says Remove any user story information from a project’s landing page (i.e. index.html). The only thing that should remain would be example usage information. - I know this is true for the example projects, but do we want to keep example usages in the boilerplates? Or just have a blank page?

[Sky020]

do we want to keep example usages in the boilerplates? Or just have a blank page?

I would definitely leave the example usages in the boilerplates -> Just remove the user stories

[Sky020]

@moT01 I think, _"publicly visible working demo"_ should be ok. I still suspect some campers will submit localhost:3000 🤷‍♂️

[ojeytonwilliams]

@moT01 I think, _"publicly visible working demo"_ should be ok. I still suspect some campers will submit localhost:3000

Seems likely. Can we catch those with validation?

[Sky020]

Can we catch those with validation?

@ojeytonwilliams Not in any way I can think that would not hinder development...

I frequently submit local URLs before finally pushing a test-passing project to something like Heroku to submit the challenge.

Although...perhaps we could interrupt on-submission, if the URL contains a local location? Just leave the tests able to run as is.

[moT01]

I feel like I would rather just word it so it is understandable instead of trying to add code for that. What about this...

When you are done, make sure your project is hosted somewhere public and submit the URL to your working demo in the Solution Link field. Optionally, submit a link to your projects source code in the GitHub Link field.

When you are done, make sure a working demo of your project is hosted somewhere public. Then submit the URL to it in the Solution Link field. Optionally, also submit a link to your projects source code in the GitHub Link field.

[moT01]

It says in the issue - "Once all changes have been deployed, the README.mds for each project in the demo-projects repo will be deleted." - do we want to remove those readme's on the demo projects or give them a link to the learn page like we're doing for the boilerplates? I am leaning towards having a link.

[Sky020]

do we want to remove those readme's on the demo projects or give them a link to the learn page like we're doing for the boilerplates?

I thought the thinking behind this was, there should be no way a camper will end up on a demo-project README. So, remove them?

[SaintPeter]

I'll remove the READMEs from the various Boilerplate Demo Project PRs I have open.

[Sky020]

@SaintPeter To clarify: It is not the READMEs in the boilerplates that need to be removed...it is the READMEs in the demo-projects which need to be removed.

[ojeytonwilliams]

I frequently submit local URLs before finally pushing a test-passing project to something like Heroku to submit the challenge.

Although...perhaps we could interrupt on-submission, if the URL contains a local location? Just leave the tests able to run as is.

Good point. We could always disable the submit button if we detect localhost, but that's definitely something that's nice to have, rather than urgent.

[moT01]

Most of the PR's I have just stick to the issue. There's a number of other things I would like to do to the boilerplates and demo projects...

• Change the favicons
• Make all the titles uniform
• Make a uniform layout where we can - basically just have the project title and an hr
• Remove old assets (glitch/hyperdev, .gitconfig file)
• Create a .gitignore with a few things in it
• Maybe a uniform footer

Wondering if that is getting to be too much or we can tack on some of this to these PR's. I already added some to the timestamp PR's, but I am going to hold off on the others for now. I know there's some bigger PR's out there that existed before this issue - those are fine. I'm thinking if we can add them on to these PR's, it will be one less round of reviews and PR's to create.

[SaintPeter]

@moT01 Give me some standards and a favicon.ico file and I'll be happy to update my many PRs to include them. I've been doing cleanup to the best of my ability, but I didn't want to poke stuff I wasn't familiar with.

[ojeytonwilliams]

Is there any way we can DRY this out? There's a lot of repetition in the boilerplates that it would be nice to centralise, but I'm not sure if there's a simple way.

Submodules should work, but then users would need to work with them and that's a bit of a pain. Does anyone know of a better approach?

[moT01]

Not even sure how submodules would work - we could have one per project, use it for basically all the boilerplate - then just add the submodule and additional code for each example project. Not sure if that actually helps or just complicates it in a different way. Most of these boilerplates and example projects do share a lot of code, but not all of them and many of the ones not on here, don't. I kind of feel like we should continue with this how it is and maybe bring that up in another issue. Not too familiar with submodules to be honest, so I'm not quite sure how it would work or the best way to use them.

Here's what I put on my timestamp PR @SaintPeter https://cdn.freecodecamp.org/universal/favicons/favicon-32x32.png - I think that should be fine?

[nhcarrigan]

I believe we've caught them all, but just in case we missed any... an extra set of eyes to ensure there are no InfoSec related stories/tests on the QA projects would be greatly appreciated 😁

I closed #39435 to roll in to this issue.

[moT01]

Do we want to try to incorporate these additions to the PR's already out there for adding tests? or should we keep them separate? Perhaps it's best to just keep them separate.

[ojeytonwilliams]

Not even sure how submodules would work

The approach would be to have the common stuff (package.json, dotenv, express etc.) in a single repo. Each project would have their own repos and be imported into the common one.

Not sure if that actually helps or just complicates it in a different way.

Probably the latter, but I figured there was some chance it was a sensible approach and I'm not keen on the amount of code repetition. That said, the cure could be worse than the disease.

Anyway, I don't want to derail the conversation, so I'll leave it at that!

[nhcarrigan]

The removal of the infosec should be handled, but never hurts to double check.

Adding the favicon and other changes could potentially be done in the same PRs, but I'd be concerned about the large scope - the more we handle in a single PR, the easier it is to miss a change right? 🤔

[SaintPeter]

See above for Issue Tracker Boilerplate and Demo Project updates.

[nhcarrigan]

Alright - I pushed out PRs to hit the Stock Price checker and Message Board projects. 🙂