WEBVTT

NOTE Created by CaptionSync from Automatic Sync Technologies www.automaticsync.com

00:00:01.016 --> 00:00:04.976 align:middle
The last TODO for our PR is
to create a documentation PR.

00:00:05.366 --> 00:00:11.666 align:middle
And, honestly, in my opinion, making changes
to the documentation is probably the easiest

00:00:11.986 --> 00:00:16.076 align:middle
and most effective way to contribute to Symfony!

00:00:16.686 --> 00:00:22.056 align:middle
There are tons of great ways to help the docs,
even if you're not documenting a new feature.

00:00:22.056 --> 00:00:27.116 align:middle
For example, imagine you're reading
the docs - like the forms page.

00:00:29.236 --> 00:00:33.036 align:middle
Then, you find something
that's inaccurate or confusing.

00:00:34.206 --> 00:00:39.976 align:middle
Well, just go back to the top, click "Edit this
page", and you'll be inside an editor on GitHub

00:00:40.146 --> 00:00:43.566 align:middle
where you can make improvements
and create a pull request.

00:00:44.426 --> 00:00:47.006 align:middle
I've worked on the documentation for years.

00:00:47.466 --> 00:00:50.866 align:middle
And the best way to improve
it is to get feedback

00:00:50.916 --> 00:00:53.306 align:middle
from real people who are trying to use it.

00:00:54.086 --> 00:00:59.546 align:middle
Taking a few minutes to reword a
paragraph could save someone else hours.

00:01:00.216 --> 00:01:01.426 align:middle
That's pretty cool.

00:01:02.516 --> 00:01:04.046 align:middle
Go back to the homepage of the docs.

00:01:04.616 --> 00:01:08.886 align:middle
Copy the clone URL: let's clone
this down onto our machine.

00:01:09.616 --> 00:01:13.426 align:middle
At your terminal, move back into
the main contributing directory

00:01:13.566 --> 00:01:16.206 align:middle
and run git clone and paste.

00:01:17.436 --> 00:01:23.056 align:middle
I'll also go to PhpStorm and move us back
into this main contributing/ directory

00:01:23.346 --> 00:01:29.256 align:middle
so we can see all of the test projects,
symfony itself and the new symfony-docs folder.

00:01:30.556 --> 00:01:34.066 align:middle
Ok: we want to document our
new TargetPathHelper.

00:01:35.116 --> 00:01:36.596 align:middle
Great! Except...

00:01:36.846 --> 00:01:39.326 align:middle
where should these new docs live?

00:01:40.146 --> 00:01:43.746 align:middle
This can be a real challenge: the docs are huge!

00:01:43.746 --> 00:01:48.706 align:middle
If you're not sure, don't worry: just
choose some place that makes sense to you.

00:01:48.706 --> 00:01:54.866 align:middle
If there's a better place, someone will tell
you when reviewing your PR and you can move it!

00:01:55.926 --> 00:01:58.506 align:middle
Head back to your terminal
and move into symfony-docs.

00:02:02.146 --> 00:02:05.246 align:middle
Because this feature builds
off of TargetPathTrait,

00:02:05.676 --> 00:02:12.576 align:middle
let's see where that's documented:
git grep TargetPathTrait Ok:

00:02:12.716 --> 00:02:17.466 align:middle
apparently that's covered
in some form_login.rst file.

00:02:19.176 --> 00:02:24.106 align:middle
Go find that in PhpStorm:
security/form_login.rst.

00:02:25.646 --> 00:02:27.866 align:middle
Look all the way down at the bottom.

00:02:29.906 --> 00:02:33.246 align:middle
Yep, here is where it talks
about TargetPathTrait.

00:02:34.286 --> 00:02:37.836 align:middle
We'll add a few more details
below this about our new class.

00:02:39.146 --> 00:02:44.576 align:middle
But wait! When I first opened this document,
I noticed something interesting on top.

00:02:45.656 --> 00:02:49.696 align:middle
It describes how this "target
path" feature works in general.

00:02:50.326 --> 00:02:55.106 align:middle
Then, there's a note below:
sometimes redirecting

00:02:55.106 --> 00:02:58.276 align:middle
to the originally requested
page can cause problems,

00:02:58.746 --> 00:03:03.986 align:middle
like if a background AJAX request
appears to be the last visited page,

00:03:04.346 --> 00:03:07.206 align:middle
causing the user to be redirected there.

00:03:07.906 --> 00:03:08.816 align:middle
That makes sense...

00:03:09.186 --> 00:03:11.346 align:middle
except, it's not true!

00:03:11.886 --> 00:03:17.556 align:middle
Nope, this note is out of date:
Symfony no longer has this problem.

00:03:17.556 --> 00:03:20.696 align:middle
I think I just found a documentation bug!

00:03:21.886 --> 00:03:25.926 align:middle
Let's make sure: go to
github.com/symfony/symfony.

00:03:26.886 --> 00:03:30.806 align:middle
Then press "t" to open the
"file search" and look

00:03:30.806 --> 00:03:34.646 align:middle
for a class called ExceptionListener
from the Security/ component.

00:03:37.236 --> 00:03:41.126 align:middle
This is the class that's responsible
for setting the target path.

00:03:41.126 --> 00:03:44.996 align:middle
It happens all the way down at
the bottom in setTargetPath().

00:03:44.996 --> 00:03:52.216 align:middle
If you go to a page like /admin as an
anonymous user, right before you're redirected

00:03:52.216 --> 00:03:55.496 align:middle
to the login page, this setTargetPath()
method is called.

00:03:55.496 --> 00:03:57.186 align:middle
And, cool!

00:03:57.606 --> 00:04:01.526 align:middle
This uses the method from
TargetPathTrait, just like we did.

00:04:02.216 --> 00:04:08.626 align:middle
But, check it out, it checks to see
if the request is an AJAX request -

00:04:09.346 --> 00:04:12.796 align:middle
that's the isXmlHttpRequest() part.

00:04:12.796 --> 00:04:19.216 align:middle
If it is an AJAX request, it does
not set the URL into the session.

00:04:20.026 --> 00:04:22.796 align:middle
Yea! The documentation is wrong!

00:04:23.586 --> 00:04:26.956 align:middle
The question now is: how old is this bug?

00:04:27.446 --> 00:04:33.956 align:middle
How long ago was this changed in Symfony and
what versions of the docs do we need to update?

00:04:35.076 --> 00:04:36.596 align:middle
Head back to the Symfony Roadmap.

00:04:38.036 --> 00:04:42.436 align:middle
The three maintained branches
are 2.8, 3.4 and 4.1.

00:04:43.516 --> 00:04:46.326 align:middle
Remember: when fixing a bug, you should fix it

00:04:46.326 --> 00:04:50.736 align:middle
in the oldest maintained
branch where the bug exists.

00:04:50.736 --> 00:04:52.236 align:middle
The same is true for the docs.

00:04:53.196 --> 00:04:57.796 align:middle
To figure out when the fix was made
to Symfony, let's git blame this file.

00:04:58.876 --> 00:05:00.026 align:middle
Scroll back down to the bottom.

00:05:01.286 --> 00:05:05.626 align:middle
Hmm, so this line was last
modified two years ago.

00:05:06.246 --> 00:05:12.476 align:middle
And if you look at that commit, its changes
do not include the AJAX part of this line.

00:05:13.226 --> 00:05:17.516 align:middle
Yep, the change we're looking
for is more than two years old.

00:05:18.106 --> 00:05:22.116 align:middle
And this commit was first
included in Symfony 2.7!

00:05:23.216 --> 00:05:29.706 align:middle
In other words, the AJAX fix has
existed since Symfony 2.7 or earlier.

00:05:30.306 --> 00:05:33.856 align:middle
But, because Symfony 2.7
is no longer maintained,

00:05:34.236 --> 00:05:37.756 align:middle
we'll fix this on the 2.8 branch of the docs.

00:05:38.646 --> 00:05:44.306 align:middle
Then, after our pull request is merged,
our changes will be merged up into all

00:05:44.306 --> 00:05:46.406 align:middle
of the newer branches by the docs team.

00:05:47.676 --> 00:05:50.886 align:middle
Awesome! Find your terminal
and create the new branch:

00:05:51.416 --> 00:06:00.136 align:middle
git checkout -b remove-outdated-note
origin/2.8 Move back to the file.

00:06:00.986 --> 00:06:04.726 align:middle
Yep, that bad note did exist even back then.

00:06:05.536 --> 00:06:11.956 align:middle
And, woh! It links to a whole other document
that describes how to work around this problem.

00:06:12.946 --> 00:06:14.886 align:middle
We can delete all of this!

00:06:15.456 --> 00:06:16.576 align:middle
Remove the note first.

00:06:20.336 --> 00:06:28.156 align:middle
Then delete that other file: git
rm security/target_path.rst And...

00:06:28.156 --> 00:06:28.666 align:middle
we're ready!

00:06:29.646 --> 00:06:36.266 align:middle
git statusgit add -ugit commit Describe
why we're deleting all this stuff.

00:06:40.546 --> 00:06:42.156 align:middle
Ok, the code is ready!

00:06:43.406 --> 00:06:47.176 align:middle
Head back to GitHub and fork the
repository if you haven't already.

00:06:51.606 --> 00:06:59.226 align:middle
Then, copy your git URL and add your
remote: git remote add weaverryan and paste.

00:07:00.386 --> 00:07:01.696 align:middle
Now, push!

00:07:02.106 --> 00:07:08.956 align:middle
git push weaverryan remove-outdated-note
Move back and...

00:07:09.066 --> 00:07:11.446 align:middle
if you're lucky, you'll see a yellow bar.

00:07:12.936 --> 00:07:14.866 align:middle
We are lucky this time!

00:07:15.456 --> 00:07:17.236 align:middle
Click "Compare and pull request".

00:07:18.346 --> 00:07:23.586 align:middle
Oh, but hmm: why are there two
extra commits by other people?

00:07:24.106 --> 00:07:27.776 align:middle
Ah, because we need to change
our base branch to 2.8.

00:07:29.046 --> 00:07:30.076 align:middle
Much better.

00:07:30.926 --> 00:07:35.156 align:middle
In the description, we want to make
this as easy as possible to merge.

00:07:35.596 --> 00:07:40.836 align:middle
So, let's describe why we're removing this
and that we checked the code to be sure.

00:07:41.986 --> 00:07:43.366 align:middle
Ok... submit!

00:07:46.636 --> 00:07:49.546 align:middle
The docs also have a continuous
integration system.

00:07:50.406 --> 00:07:53.476 align:middle
I want to talk about that next,
write our new documentation

00:07:53.756 --> 00:07:55.836 align:middle
and learn a bit about the docs format.