Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

How to add new material #614

Open
mikeshulman opened this Issue · 11 comments

5 participants

@mikeshulman
Owner

Supposing we want to add new mathematics, let's discuss how to do it in a new thread. Some possibilities:

  • Create a branch for the second edition and make all changes there directly. Errata for the first edition are periodically merged in from the master branch. When we are ready to release a second edition, we simply merge the second-edition branch back into master.

  • As suggested by Vladimir at #601, create an "additions" document for new additions. Then when we are ready to release a second edition, we manually place all of these new additions where they ought to go in the book.

I feel like if and when we are seriously ready to work on the second edition, we'll need to go for the first option eventually anyway: merging in the new additions will probably require work over a period of time. But I do see the advantage of the second choice at first, in that it gives current readers an easy way to see what's being added.

@andrejbauer
Owner

Without a doubt we should follow the open source community here. Which means that we would branch, what Vladimir proposes would make sense if we did not have Github.

But the old version should be branched off into 1st-edition, while the development of the second edition should take place on master. As far as I understand the open-source community, master is supposed to be where the bulk of current development takes place. Branches are there for keeping old versions around, for alternate developments, and for temporary branching (to submit a pull request, or to perform a non-trivial amount of changes).

And until somebody actually starts working on the 2nd edition there is no reason to branch.

@mikeshulman
Owner

I am curious why it makes a difference which branch is called "master". Internally in git, there is no difference between a branch called "master" and a branch called "2nd-edition" other than their names, is there?

@EgbertRijke
Collaborator
@andrejbauer
Owner

There are various settings which default to master unless otherwise specified. I'll try to figure out whether the open source community has good reasons for their scheme (and whether I got it right). Actually, there ought to be some lurkers around here who can chime in.

@JasonGross
Owner
@mikeshulman
Owner

Github certainly treats "master" specially, but does git treat it specially in software (not just users' conventions)?

@JasonGross
Owner
@mikeshulman
Owner

On github, when I push changes to a branch in my fork and then click "compare and pull request", by default it compares to the "master" branch of the main repository. Is that just because "master" is set as the "default" branch of that repository, and if it were set to something else it would do the comparison to that branch?

But anyway, the question is about more than naming. My inclination was to have the first-edition branch be the "default" one, and I thought that that would actually be less confusing. Suppose, for instance, that mathematician X is reading the publically available version of the book (which is a recent release of the first edition), notices a typo, and wants to fix it for us. If the default branch is the first edition, then he can just make a fork, look through the source (which is the same as the source for the printed version he has in front of him) for the typo, fix it, and submit a pull request.

But if the default branch is the second edition, then when X makes his fork, the source he's looking at by default will not correspond to the printed version in front of him. Maybe the second edition has been reorganized, and the paragraph containing his typo has been moved into a different chapter. How is he supposed to find and fix it, without having been a part of all the development of the second edition? Of course, he could manually check out the first-edition branch instead and submit his pull request on that, but that requires more git-fu than I would like to ask of potential typo-fixers.

@krakrjak
@JasonGross
Owner
@mikeshulman
Owner

Perhaps the conclusion should be to put off the decision until we have a clear picture of what exactly the second edition will be (or even if it will exist at all), and who will be writing it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.