Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Drop lesson_initialize.py #287

Open
rgaiacs opened this Issue Jun 2, 2018 · 14 comments

Comments

Projects
None yet
6 participants
@rgaiacs
Copy link
Collaborator

rgaiacs commented Jun 2, 2018

lesson_initialize.py has annoyed me for two years because (1) it made hard for maintainers of the lessons to incorporate changes on the files that were hard coded in the script and (2) it requires that new lesson creators have Python on their machine. #260 resolved (1) but and this proposal will resolve (2). The suggestion were made by @jduckles.

Implementation Details

  1. Create a new branch called vanilla.
  2. Change the default branch of this repository to be vanilla.
  3. Copy the content of bin/boilerplate to . on the gh-pages branch.
  4. Create a pull request to https://github.com/swcarpentry/lesson-example covering this changes, i.e. removing references to lesson_initialize.py.

Benefits

  1. Lessons creator only need to import this repository to start a new lesson.

    The default branch on the new created lesson/imported repository will be gh-pages

  2. Contributors to this repository will, by default, send pull requests to vanilla.

  3. When a new lesson is release, vanilla will be merged into gh-pages so that new lessons use the latest stable version.

  4. Update of existing lessons will be similar with how we do now except that maintainers will merge vanilla instead of gh-pages.

Drawbacks

  1. Two branches on the repository. As mentioned at the previous section, lesson authors will have gh-pages as the default branch so this should not be a problem for them.

FAQ

  1. Why do you use "vanilla" for the new branch?

    Because we need to use a name that when sorted alphabetic will be after gh-pages and be meaningful. "vanilla" satisfies both criteria and also is "a substance made from the seeds of a tropical plant, used to give flavour to sweet foods" (https://dictionary.cambridge.org/dictionary/english/vanilla).

Request for Feedback

@rgaiacs rgaiacs added the enhancement label Jun 2, 2018

@rgaiacs rgaiacs added this to the v9.5.1 milestone Jun 2, 2018

@brownsarahm

This comment has been minimized.

Copy link
Contributor

brownsarahm commented Jun 2, 2018

Maybe I'm missing something but I don't understand how the actions of lesson_initialize are solved by what's in this proposal?

@rgaiacs

This comment has been minimized.

Copy link
Collaborator Author

rgaiacs commented Jun 3, 2018

@brownsarahm I missed one step.

Copy the content of bin/boilerplate to . on the gh-pages branch.

I updated the first comment to include it.

@fmichonneau

This comment has been minimized.

Copy link
Member

fmichonneau commented Jun 13, 2018

+1 on this proposal. I don't think it makes sense to have the boilerplate text in each repository when the repository is created. It seems that it will also make it easier to push changes to repository-specific files.

@jduckles

This comment has been minimized.

Copy link
Member

jduckles commented Jun 13, 2018

+1 from me! Helping people copy the repo and hit the ground running has been a goal of mine since I dug into how this process works. Thank you for the clearly laid out proposal @rgaiacs

@ErinBecker

This comment has been minimized.

Copy link
Contributor

ErinBecker commented Jun 13, 2018

+1 from me. This looks like it will really help!

@maxim-belkin

This comment has been minimized.

Copy link
Collaborator

maxim-belkin commented Jun 14, 2018

My apologies, but I'm not sure I understand how what is proposed is related to the described problem.
Whenever downstream (actual lesson) is going to merge changes from upstream (this repo), they will have to deal with changes made to the files that this repository introduces (either with lesson_initialize or any other way).

Other thoughts:
Point 2 under Implementation Details states:

Change the default branch of this repository to be vanilla

Whereas point (1) under Benefits says:

The default branch will be gh-pages

Also, from the OP I got the impression that all files from boilerplate will be simply moved to the root of the repository whereas @fmichonneau says that it does not makes sense to have the boilerplate text in each repository...

@rgaiacs

This comment has been minimized.

Copy link
Collaborator Author

rgaiacs commented Jun 14, 2018

@maxim-belkin Thanks for the valuable feedback.

Whenever downstream (actual lesson) is going to merge changes from upstream (this repo), they will have to deal with changes made to the files that this repository introduces (either with lesson_initialize or any other way).

You are right. Maintainers will still need to deal with some changes manually. #260 improved what we could do. Before was hard to see the difference in the files. Now, maintainers can do something like

$ git diff X.X.X--Y.Y.Y bin/boilerplate/some-file.md

and get the difference so they can apply it to the files. Is possible to have one script to get the diff and apply to the desired file but I would not invest time on this now.

I clarified your comment about vanilla vs gh-pages. Please have a look. On the Benefits section, I was talking about the new created repository.

Also, from the OP I got the impression that all files from boilerplate will be simply moved to the root of the repository whereas @fmichonneau says that it does not makes sense to have the boilerplate text in each repository...

Move might be one interesting option but I need to check how Git will handle this after a couple of commits.

@rgaiacs rgaiacs modified the milestones: v9.5.1, v9.6.0 Jun 14, 2018

@maxim-belkin

This comment has been minimized.

Copy link
Collaborator

maxim-belkin commented Jun 14, 2018

I see. So, we are talking about 2 things here:

  • Starting a new lesson
  • Merging changes (made to "boilerplate files" in styles repo)

OK, let's compare the procedures.


Starting a new lesson (1-time "thing")

Now:

  1. Import carpentries/styles repository
  2. Run lesson_initialize

pros: files that have to be worked on are all "untracked", so it is easy to see what has to be done
cons: requires Python

Proposed:

  1. Import carpentries/styles repository
  2. Change the default branch from vanilla to gh-pages

pros: independent of Python
cons: not immediately obvious which files to work on (though FIXMEs should help)


Merging changes from upstream (performed regularly)

Now:

  1. Merge changes from upstream
  2. (Somehow) Identify changes made to boilerplate files (🙄)

cons: see 2

Proposed:

  1. Merge changes from upstream

cons: N/A ?


Other thoughts:

  1. I find it convenient to have "untracked" files when I run lesson_initialize because this way I see files I have to work on. If Python nature of lesson_initialize is an issue, we can rewrite it to Bash.
  2. We can move all boilerplate files to where they are supposed to be, and change lesson_initialize to add FIXME to them (or something along these lines) so that when it is executed we see what files have to be processed.
  3. I'm not a big fan of adding a branch to this repository and, at least to me, the choice of its name -- vanilla -- seems confusing because plain vanilla is usually something in a clean/pristine state, whereas in this proposal this is some sort of a "development" branch. I'm also not sure why its name has to appear after gh-pages when sorted alphabetically.

In summary, I think it might be easier to:

  1. Rewrite lesson_initialize in Bash
  2. Move boilerplate files to where they are supposed to be
  3. Change the behavior of lesson_initialize to mark files the lesson creator has to work on
@rgaiacs

This comment has been minimized.

Copy link
Collaborator Author

rgaiacs commented Jun 14, 2018

I find it convenient to have "untracked" files when I run lesson_initialize because this way I see files I have to work on. If Python nature of lesson_initialize is an issue, we can rewrite it to Bash.

The main point is that we want to make possible for people to start new lessons only using the web browser. If people get to the point of contribute a lot they will download Git to work locally and eventually have Jekyll so they can test their lesson locally before push to GitHub.

I'm not a big fan of adding a branch to this repository and, at least to me, the choice of its name -- vanilla -- seems confusing because plain vanilla is usually something in a clean/pristine state, whereas in this proposal this is some sort of a "development" branch. I'm also not sure why its name has to appear after gh-pages when sorted alphabetically.

The name has to appear after gh-pages because the default branch on the new repository will be the first one that GitHub lists. Users should have the files they need to edit at https://github.com/carpentries/some-lesson/ instead of https://github.com/carpentries/some-lesson/tree/some-branch.

@maxim-belkin

This comment has been minimized.

Copy link
Collaborator

maxim-belkin commented Jun 14, 2018

Oh, I see! So, the goal is to have 100% web-based lesson development. That's interesting.

Regarding default branches: the default branch for any repository is set under /settings/branches. For this repository, for example, the default branch can be set here:
https://github.com/carpentries/styles/settings/branches

And regarding web-based development: we just have to move all the files to their proper locations, add FIXME to files that have to/must be changed, and provide instructions how to set up Travis that would "fail" the build if it finds any FIXME comment.

@rgaiacs

This comment has been minimized.

Copy link
Collaborator Author

rgaiacs commented Jun 14, 2018

Regarding default branches: the default branch for any repository is set under /settings/branches.

True. But GitHub doesn't respect it when you import the repository. For example, if your repository has branches dev, gh-pages and master being master the one the default when you import it the default branch on the imported repository will be dev and not master.

@maxim-belkin

This comment has been minimized.

Copy link
Collaborator

maxim-belkin commented Jun 14, 2018

Hmmm, this is weird but it works differently for me: I've just imported https://github.com/carpentries/assessment (it took a WHILE) and the default branch was still set to master even though there is a bunch of branches such as add-license-1, add-plot, erin-trash (WAT? 🤣)

@brownsarahm

This comment has been minimized.

Copy link
Contributor

brownsarahm commented Jun 15, 2018

This seems like a good idea to me also

I think that we should also add a README to the vanilla branch that gives the lesson developer a bit more contained instructions about how to use this, noting which files that need to be changed and keeping resources in a place where they would see it. Thegh-pages branch may stay as boileerplate/README.md currently or have an section like:

START HERE: remove this once you've done it
[] checklist of steps to get lesson started
edit these files, etc

@maxim-belkin

This comment has been minimized.

Copy link
Collaborator

maxim-belkin commented Jun 17, 2018

OK, my comments:

  1. 👍 on moving files from /bin/boilerplate to where they are supposed to be (in the gh-pages branch)
  2. 👎 on creating a new vanilla branch and related changes. I don't see any need for it nor I understand how it is going to be useful.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.