Comments (19)
On Sun, Mar 15, 2015 at 06:19:13AM -0700, Ivan Gonzalez wrote:
I think that, without going into much details, a good explanatory
sentence in the part of the lesson where the first commit is created
would be nice.
Either from this sentence or from the glossary entry, I think we
should link to Tim Pope's note 1, since that's the best balance of
clear, concise guidelines and the reasoning behind them that I've
found.
The main goal of a commit message is motivating the change, and I
really like Justin Hileman's “How to Git pretty” 2 for its emphasis
on creating clear, understandable history. No amount of commit
message composition will make it easy to understand a huge commit
making multiple orthogonal changes ;). Rewriting history may be too
big a step for novices struggling with creating history at all, but I
don't think it's so big a step that we can't link to that talk from
somewhere later in the lesson.
from git-novice.
from git-novice.
On Sun, Mar 15, 2015 at 09:31:06AM -0700, Greg Wilson wrote:
We could ask Pope and Hileman if we could incorporate their text
into our lesson (with attribution).
I don't think we actually want more than a sentence explaining that
you should compose your commit message with an eye towards a concise,
unique summary, followed by a body with motivation and implementation
details. All of the long-line stuff, imperative phrasing, etc., is
nice, but in my opinion not important enough for space in the lesson
itself. I'd rather have the single sentence with a link then embed
Pope's example and surrounding text.
We probably can't embed Hileman's stuff, since it's a slide show. I
don't think we want to embed it either, since again, I don't think the
novice lesson gets folks to the point where I'd want to talk about
rewriting history. At least, I'd want them to have some quality time
with the novice material to let the concepts gel before getting into
rewriting.
from git-novice.
from git-novice.
I'm not sure that I agree that we need to spend time explaining best practices for commit messages. Really, if we're starting people with collaborating with themselves for their own future edification, all we need to teach is "write something that will make sense to future you" and then they should be able to figure it out from there.
from git-novice.
On Sun, Mar 15, 2015 at 03:26:18PM -0700, Daisie Huang wrote:
I'm not sure that I agree that we need to spend time explaining best
practices for commit messages.
I think the only proposed change to the taught lessons here is a
single sentence suggesting folks think about a clear, concise summary
and optional follow-up motivation/implementation details. We should
probably just submit that in its own PR. Does anyone want to work
that up? I'll handle it if nobody else wants to.
After the taught sentence (about which I think everyone agrees),
there's disagreement on where to store additional follow-up
information. My preference is to link-out to external sites.
@gvwilson wants to inline the external docs in discussion.md, and
@iglpdc suggests a glossary entry. I think we can continue to hash
that out here while the taught sentence lands through a different PR.
… and then they should be able to figure it out from there.
Just because they could figure it out on their own doesn't mean we
can't help them along by pointing interested parties at good
references. It's harder to sort the wheat from the chaff when you're
new to a topic.
from git-novice.
from git-novice.
On Mon, Mar 16, 2015 at 11:37:28AM -0700, Greg Wilson wrote:
I would really like to have a short example in our notes - it'll
take 2-3 minutes of class time, and would add a lot of value.
I think the current preference for the one-line commit messages is
because we're trying to stay on the command line and out of the
possibly-unfamiliar editor. Folks likely just learned about the
command line (maybe a few hours before this lesson), and may have
never seen their local text editor either. Sometimes it's too awkward
to avoid using the editor (e.g. I don't think we want to use >>
redirects to add content to mars.txt ;), but ‘git commit -m '…'’ works
well enough that I'm not sure it's worth dragging complete novices
into an editor to walk them through composing a good commit message.
I think spending a few minutes live-coding a good commit message and
pointing out its features does make sense if the students are more
comfortable in their own editors, but I'm fine leaving that up to
instructor initiative. A link to Tim Pope's post should give them
sufficient background on the technical considerations, so I'd rather
not rehash that locally. I'd be fine with a bit of additional patter
explaining the intended audience (reviewers and future devs, which may
include your future self) and the intended message (a summary of the
change, motivational details, possibly notes on tricky implementation
issues, notes on alternative implementations and why they were
rejected, …). Maybe a callout box? Or a long-form discussion entry
(see swcarpentry/DEPRECATED-lesson-template#199).
In any case, if we go with a longer-form discussion, I think we want
to make it something that an instructor has to opt into, and not
something that's part of the default lesson flow. Personally, I'd
rather move the longer discussion into an intermediate Git lesson,
since it's a lot easier to motivate these messages if the students
have already internalized the general flow and you're really focused
on tuning the feature branch, code review, and project maintenance
workflows.
from git-novice.
I definitely agree that this is something very useful for the intermediate Git lesson.
from git-novice.
On Mon, Mar 16, 2015 at 1:23 PM, W. Trevor King [email protected]
wrote:
We should
probably just submit that in its own PR. Does anyone want to work
that up? I'll handle it if nobody else wants to.After the taught sentence (about which I think everyone agrees),
there's disagreement on where to store additional follow-up
information. My preference is to link-out to external sites.
@gvwilson wants to inline the external docs in discussion.md, and
@iglpdc suggests a glossary entry. I think we can continue to hash
that out here while the taught sentence lands through a different PR.I totally agree. I think that we could do two PRs, one for with a
sentence in the main lesson, and another one with a longer discussion, be a
glossary entry, a link to external stuff to whatever.
@wking, do you mind if I send out an email to discuss to see if a new
instructor wants to take care of the short sentence one? I think it's easy
enough, given that you posted here most of the relevant links, and could be
a good first PR for someone. We can wait a couple of days and if nobody
shows up, you do it.
from git-novice.
On Tue, Mar 17, 2015 at 08:12:51AM -0700, Ivan Gonzalez wrote:
@wking, do you mind if I send out an email to discuss to see if a
new instructor wants to take care of the short sentence one? I think
it's easy enough, given that you posted here most of the relevant
links, and could be a good first PR for someone. We can wait a
couple of days and if nobody shows up, you do it.
Sounds good to me :).
from git-novice.
I'd be interested in doing this :)
from git-novice.
All yours, @janepipistrelle. Let us know if you need help.
from git-novice.
Okay, I've had a go. If it hasn't worked, I've done something wrong (first time doing a PR here!).
from git-novice.
Closed by #78.
from git-novice.
On Tue, Mar 24, 2015 at 06:49:31PM -0700, Ivan Gonzalez wrote:
Closed by #78.
Maybe not. Is there still disagreement about if/where to store more
detailed local docs 1? I'm happy after #78, but that was only part
of the solution for some other participants in this issue.
from git-novice.
You're totally right! Thanks for catching this. Reopening.
from git-novice.
A picture to accompany the discussion will show students what bad messages look like and hopefully show them not to do it
https://xkcd.com/1296/
https://twitter.com/chendaniely/status/588826374208618496
from git-novice.
I'm closing this in favor of #190.
from git-novice.
Related Issues (20)
- GH settings screen shot is out of date
- Is there a supplemental SSH episode?
- We contradict our own advice about forgetting about ssh keys
- Suggest flipping order of git clone screenshots
- Share what to do if you already have an ssh key HOT 2
- Episode time allotment is inaccurate HOT 4
- Note that there is no response when typing password/pass phrase/etc in your terminal HOT 1
- "AFK" may not be a recognizable term to everyone
- README goes to the old lesson template
- Creating a new branch or renaming the default branch HOT 3
- Consider updating CONTRIBUTING to require forking regardless of privileges HOT 2
- Misleading Interplay between Episode 4 and 5 HOT 1
- file versions are not saved; changes to files are tracked/recorded HOT 1
- Add note about how rm from command line is irrecoverable HOT 1
- git config `core.autocrlf` option is incorrect
- Maintainer mismatch with website HOT 3
- Move SSH key creation (7.3) to Lesson 2 - Setting Up Git HOT 4
- Connect to preliminary material: Good Enough Practices HOT 3
- Do not mention branches while creating the first repository?
- Broken reference in citation episode
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 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.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
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.
from git-novice.