Microsoft 365 Community Community Demos, 18 Jun 2019

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Getting Started Helping with PnPjs v2

Description

Informal overview of getting started helping contribute to PnPjs v2. Recorded from a call on June 14th, 2019.

Learn more: https://github.com/pnp/pnpjs/blob/dev-v2/README.md

A

Hey Patrick, don't forget to start recording thanks, buddy yeah. You got it this.

B

Is gonna be a pretty informal session, but I wanted a chance for folks to kind of get an introduction to what it means when we say hey, who wants to help with doing some peen PJs version to work, so we're gonna, take a look at doing that today. Hey that's what we're in right now so to start with, I've got my project down here and we're forked and I'm. Assuming at this point folks have got a development environment set up, and so we're not gonna. We're not gonna.

B

Do that part of this I'm gonna assume you've got your development environment. You know how to fork a repo and so forth, but one of the first things- and this is something Julie actually pointed out yesterday- is a great thing to mention. Is we should always before we start?

B

We should refresh our local copy from the upstream source, so I have a fork right in my Patrick Rodgers part of github and I need to pull the latest code from the main P and pj s, part of github, and the way you do that is just do a pull command. Lets you specify your target and where you want to pull from so in my case, I have a remote called upstream, which is the PJs repo and so I'm. Just gonna hit pull and I'm already up to date.

B

Cuz I do that about a hundred times a day, but you would see maybe some changes come in just like if you did a pool to your local repository, so great, so I want to help with p.m. PJs. What do I do? What what? How do I get started? So the first thing you want to do is come to the issues list and David and Simon have done a great job of going through and creating a whole bunch of issues. So it looks like we have a ton of issues right now and we do.

B

But all of these ones that are prefixed with 2o are part of the 2o work, and so the way you get started is you come in here and say: I want to work on a sub-module Patrick. What is a sub module?

B

The great question, so this is the code and we're gonna go back to the issues list in a second but I think it's important to see in the code under the source, folder you'll see now each of the things excuse me: each of the things is a folder now, as opposed to just a file and we're gonna look at regional settings today. So I'm gonna pick on that as an example, but you can see in here it has its own index file and some other files we'll look at shortly.

B

So don't worry about those quite yet, but this is what I mean and what we are referring to is a sub-module, and these are the things that allow us to do. The selective imports in the code in the library.

B

And so what we're gonna do is say: well, I want to work on the regional settings. This is a pretty small one. I think I can handle this. There's nothing too complicated in here. I get what's going on. I want to do regional settings and I picked this one specifically for today, because it's small, so you would come in here and you would look at the issue and you're gonna see this stuff. We're gonna go over what all this means in a second, but your first step is to come in here and simply comment.

B

Hey I would like to work on this issue, and you know please sign me up and what will happen then is one of Simon, David or Julie and I'm gonna. Take a second now to introduce the three of them are and if you all care to introduce yourselves, we can. We can do that too. I think you're. All on the call Joe, let's say two things about yourselves: oh.

C

Sure, let's do that? Yes, hi I'm, Julie, Turner I work for some praxis, consulting and I'm in the Boston Massachusetts area of the United States. That's the east coast of the United States welcome everybody.

B

And then David hey.

A

Everybody, this is David Warner I am working for catapult, happy to be helping out and I live in Los Angeles he's.

B

A movie star and then Simon. If you can hear us I'm good.

D

Amen, we say: Swedish organ doesn't matter, I leave, you I believe it's Venus pathway and I work for a company called Sogeti part of Cap Gemini, so big company and yeah. You could reach out to me if you need some help or anything cool yeah.

B

So the three of them have graciously offered their time to help with this and I really appreciate it. We all really appreciate it and they've been doing great work so far and we'll continue to do so. But what will happen is one of them will come in here and in my case they didn't comment back and say anything to me because it's you know we all talk anyway, but they would say something like hey great, hey great.

B

Let us know if you need any help right and then we'll move the status from Help Wanted to in progress, and so what that means is. You are now working on that issue. So I am working on this issue, so I'm gonna do regional settings.

B

So we've created these checklists to help kind of guide you through what needs to be done or what we think needs to be done of course, as you're looking at the code in the in the different sub modules, you might see other things and if you have you know, ideas to make things a little bit better. That's of course welcome. If you're not sure just reach out, you can comment right back on this issue with hey David.

B

Well hop typing. For me this morning is not going well. Hey, David I found a thing and let's talk about changing line 213, just as an example right. You could spell things correctly if you want that's optional, but that's the kind of thing we are looking for you to be empowered to do. If you have ideas, you know, let us know, let's talk them through.

B

Please don't make any crazy changes without talking to us, but definitely want you all to have the freedom to make some changes and do something if you see opportunities to make things better, but so coming back to the checklist, the first one is pretty self-explanatory, but some of the code still has some dues in it from could be years ago. At this point there could be blocks of commented out code, and then we want to ensure all our interfaces are prefixed with an eye and wow we're good.

B

This should be now using a weight and I've just noticed that typo, so we're changing all the internals of the library to use a weight.

B

Okay, unfortunate typo there. So let's just get started and we're gonna come in here and I, don't have any to do's in this code. I know that, because I already looked so there's nothing to do here and the two dues you could either do those two dues or you could look at it and decide. This is no longer relevant, or this isn't a thing, that's important or whatever make a decision. If you want to talk it through again just comment on the issue.

B

Our other thing is commented out code, so you're gonna see blocks of code in places that are just commented out like you might see. Some properties and methods that are commented out- and there might be something here like you know- doesn't work with latest SPO or something I'm making that up. You can just delete that code. We have source control, we have version control, we don't need to keep blocks of commented out code just hanging around and then interfaces prefixed with an eye, and so I actually drag this over here.

B

So I don't have to keep flashing the screen to remind myself what we're doing so. All of these files now have sets of interfaces and we'll talk through each of these bits of code and what they mean in a second, but you want to make sure all the interfaces that are find here already have eyes in front of them, and so here's some interfaces here. Those all have eyes eyes eyes great.

B

So that's done so. You know good to go there and so the last thing is, you want to make sure we're using a weight anywhere. We can so what that means is old-style. We used to use then so we would do things like this.

B

Like I said, this is not typing, it's not going well for me. uh Oops.

B

Let's be equals null and we're just gonna say: V equals this, you know and then we might return V. This isn't good code like we would wrap this in a promise and do it correctly here, but the general idea is we were using den instead of a wait and the reason for that is a lot of stuff. Didn't support a wait when we first started this or support was spotty, but now support for a wait is pretty good and we don't have to include as much the TS helper code for awaits.

B

So, if you ever looked at the code, a few transpiled code using a wait, you got big blocks of generator code to make that a weight function. Excuse me in an environment that maybe doesn't support it. So what you can do is just rewrite code to use a weight. So what a weight does is essentially not. Essentially it does work exactly like the a sink of weight in like c-sharp, for example. So we're saying we have an operation that returns a promise and so we're just simply going to wait for that promise.

B

It's a complete and then the final thing you have to do is you have to tag that function as async, so we've got an async function, we're awaiting a result here and we're good to go. Then we can return our result so awesome. So we've done the first thing in our checklist and I'm going to check that off and so sorry was that have question cool.

B

So the next thing, our checklist is ensure that every property and method has a test. One of the things we didn't do a great job of in the past is having test coverage for everything that we're doing, and so with version 2 we're gonna make sure we have test coverage for everything. We're doing. That sounds like a very daunting task and it is gonna, be a fair amount of work, which is why we're enlisting as much help as we can get, but the tests can be fairly simple. I understand this.

B

Is you know my volunteered time you all's volunteered time? We don't need to spend 500 hours. Writing 11 million tests on regional settings, for example, so what I've done is- and this is using mocha so for those of you that might be familiar with mocha. This is a the mocha format or pattern. If you will- or you can have different sort of closures around like a describe so we're describing regional settings and up here, I'm importing some stuff expect.

B

So chai is another library, it's a testing, library, mocha and chai, and then we're importing the stuff we need from our libraries and then this test settings is we'll, take a look at in a second. But what we're saying here is if the web tests are enabled- and there are scenarios where they would not be- we want to run these tests and so we're doing that because these all make requests. So if the web tests are disabled, we don't want to run them right, I, think that makes sense.

B

So then we're simply checking to see if I invoke. The regional settings basically request the regional settings for this web. Does this promise eventually fulfill successfully? And so again this is just mocha and chai syntax. So you can look up the docs there on. You know how this, how this all works. They've got great docs, both libraries on how these different things works and how, to you know, construct these tests.

B

You can also use the other files that we've already done as a starting point as well as examples, so we're just checking to see all these things have been fulfilled. Another thing you might notice is we're using function here, instead of like arrow notation and the reason for that is the way moco works behind the scenes. It's really pretty slick, but it attaches essentially this function to a prototype, so you're gonna get of this.

B

It's associated with your op with your tests here that scoped to that test, and you have various operations off of that, for example, you can set the time out if you need a different timeout, you can set it to zero if you have a really long running operation and have no time out and there's some other things in here that you can use within your tests and you'll actually see you know in a few places where we're setting you don't need that line there.

B

We're setting the timeout and stuff like that, so just use the function notation and that's a quirk of just how Moka works. So we want to use that arrow notation will work, but we're just trying to follow the guidelines for mocha on that. So you can see we're doing a couple different little tests here. Can we select different operations?

B

You'll notice again we're not using get so. This is the invoked Keable pattern. That's going to be in version two, though that is already in version two, so the default operation. You can simply invoke as a function the actual chain of things so SP web dot regional settings- it works for any of it, so you could get you know SP dot web. You can invoke that now and get the web results without doing dot get.

B

So you can see. We've done this for the other things we're doing other operations and then I want to add a test. So let's walk through adding a test, so my test is gonna, be we want to test for get by ID. If we look back at the code and we look back at the code, look back at the code. Look back the code. So in this particular method we actually are getting back a merged result.

B

So is one of the things the library can do, but in this case getting the times mabye ID is such a quick operation that it doesn't make sense like 99 times out of a 10. Your next operation is gonna, be to load this right. So, instead of forcing people to do it, get by ID and then invoke that we're invoking that for them, assuming they're gonna, want that timezone information and then they'll get a timezone object.

B

Timezone instance, back so they're gonna get an interface that implements orders I times an I time zone and they're also going to get that's merged with now the AI time zone info, which would be go, find that yeah is here. So this is actually what comes back for each time zone. So one of the things I did as part of my work in this sub module was I actually added these interfaces. So we didn't have these before so we've added regional settings info we've added the installed language info and the time zone info.

B

So this is a data that comes back from those methods and really they should all just be partials, but I'll fix that later, so we're gonna get this merged object back, so I want to write a test that does something with that.

B

So I'm gonna call it used and in terms of what these names should be. They should just be descriptive enough that if that test is failing, we can find it. We can understand where to look and we can get it. So in writing. My tests here, one thing I can do is this function can be async that works fine with mocha and I'm gonna copy. This line, we're gonna, set it there and what I want to do is I'm gonna. Take this part out and I'm gonna say: Const.

B

Tz is a weight this so now or invoking that we're getting our timezone object back. It's gonna have data in it right. So we can do something like we can say, expect TZ to have well, we could just say, have own property and and let's go back and look what properties does time zone info have. It should have a description right so we'll say description, and then we can also- and by the way you'll see here. The intellisense does give you all those properties because we're merging the interface here.

B

So you sources, description, ID and information. So that's coming off of the two merged interfaces and then the other thing we want to do is: let's, let's expect so we have operations. We can run on that timezone object and I want to say time zone dot. Let's go back here and what's something I can do with a time zone once I have it well, I can call it. Has these two methods right, so we're already testing those methods down here.

B

So I don't really care exactly about testing them, but I do want to see I'm just gonna copy this one, but I just want to see here that this object we've got back. I am able to invoke the methods on it right because we expect that this get by ID gives us an instance merge with the data. We're gonna expect it to have a property. We're gonna expect it to do that awesome.

B

So we've written a test, we're done sort of. We have to test our test. So one of the neat things about mocha you can do. Is this only so, if you say only- and you can do this at any level, so either this level or you can do it up here, it described you can say only you could do it on multiple things. So you could have two we're gonna run two tests, three four six whatever, but we only want to run this one test right great. How do we run a test?

B

Great question, so NPM yeah, DPM, n PM test and run so in the past in version one and since we've done p.m. PJs we've used. Gulp gulp is awesome.

B

I love, gulp I have no problem with gulp, but we're no longer using gulp and we've replaced gulp with scripts NPM scripts and what really enabled that is pretty much all the tools we use now and we'll take a look at some of these in a second support code is configuration, so you can have a configuration file that is a J's file or a TS file instead of a static JSON file, so the dynamic functionality we were putting in gulp is now we're able to put in those configuration files and and just take gulp out, and that's just really about taking a dependency out of the stuff.

B

We have to keep updated every month. So certainly absolutely not a knock on gulp. So we've run our test and you can see. We've invoked this NYC mocha. Well, what's NYC NYC is a coverage tool and we'll look at the results, hopefully here in a second, and so they NYC and mocha have been built to just work to just automatically work together, which is super cool.

B

So you just your command line, is NYC mocha and we'll look at here in a second in the config files, but I'm dumping out the generated mocha config, mostly as a sanity check to myself and to anybody else using this, so I can see if the commands or the Flags I've entered have been picked up correctly as I'm using this Hey. Our one test passed, that's great and then we got a whole ton of junk.

B

What's all this junk great question, this is our coverage report, so we can see our one test passed, yay us, but we've got all this coverage stuff. So this is for those of you who might not be familiar with what code coverage means around tests. These are all of the functions and things that have tests associated with them. What's interesting about this is this report is very wrong, so we're not using this for anything at this point, but what will allow you to do as you're working on your where we are our regional settings?

B

So you can see I've been working on regional settings and these numbers, as I was working, have all gone up right. So that's kind of what we're aiming for is to increase our usage I. Think right now it says something about your tests fail. You didn't hit the global threshold of 90% coverage. You a hundred percent, ignore that for now I haven't decided what we're gonna do with this.

B

If we're even really gonna care about this coverage report, because it hasn't been super accurate so far, but you know just you can kind of ignore that for now it's not gonna. Stop you for checking in your code. It's not something that we're gonna really look at we're more concerned that you can come in here and we could see that all the tests are there cool, so I'm gonna take that only off, so we can make sure that our other tests will now all run, and but that's neat, so we've got our test.

B

It passed, which means that this operation worked. This object had this own property description and we were able to successfully invoke this method and it eventually was fulfilled right. So the reason I'm, keeping these tests simple and and want you all to keep these tests simple, is one time right. It takes a lot of time, but I want to get basic tests out there and then what will happen in the future is somebody shows up and reports an issue with time zones for something right.

B

So the first thing we'll do at that point and we're gonna start enforcing this is we're. Gonna have a you know. This is a test. This is issue one two three and this is gonna- be a test that, when rewrite it fails because the code is broken and then when we fix it, we see that this test will now pass right, so we're gonna duplicate whatever that issue is reporting, see that it's broken.

B

Do a fix see that the test now passes right, and so these tests will expand and grow kind of organically over time right, it's just too much to sit down because I know all of us have been on projects with somebody that was like. We have to have 11,000 tests. We've got to sit here and go well. What, if you know cuz there's how many time zone IDs, maybe like 50? We have to get each one. We have to test each one know they're all the same right.

B

If we can get one I assume they're, all gonna work right. So, let's not go down a rabbit hole with writing a million tests, but let's get decent good coverage of all the things just to see that they work right because I assume the SharePoint API works that if I get a successful result, I assume that I'm getting back a time zone or the collection of time zones and so forth.

B

Right I, don't need to investigate deep down into those results, or things like that here: I'm checking because I want to make sure that property is there.

B

So, let's do this pause or they questions on what we've gone over so far, I'm kind of counting on everybody here in the call to be the voice of everybody- that's not here in the call. So if I'm saying something, that's maybe not super clear, please you can! Is there something that I am window? Oh here we go. Let's see jokes, jokes, jokes! Well, hunter percent branch coverage be required for first PR on a sub module.

B

Yes, so what we are so a hundred percent coverage, not a hundred percent coverage in that report right so like we're, not gonna, look at when we review these I'm, not gonna, look here and demand or expect these numbers to be a hundred percent, because in some cases they just won't be right and in some cases like there are no tests being run for user custom actions right now and it's a hundred percent. So this isn't going to be what we look at what we're gonna look at yeah.

B

This is a this is also a v2 requirement. So the second question there. So what we're gonna look at when we review these is I'm gonna literally open this file. So this is regional settings and I'm gonna go through here and be like alright there's these three things here: cool we're, calling those three things right and and really just eyeball it and that's how we're gonna verify it, and if we see something missing, we'll just comment on your PR and be like hey cool: can we you know, can you add a test for XYZ right?

B

So on branching we should branch from dev v2 and PR deputy? Yes. So if you are working on D, the dev branch and the dev v2 branch have no relationship, you can't go back and forth between the two. The dev D branch is completely set, so you'll want to just pull down the repo switch to the dev v2 branch in your fork. Do your work there and then send your PR back to the dev v2 branch at the upstream or at the origin. However, you want refer to that.

A

It's a really good question: I'll get that added to the to the readme and just for for anybody else. You've probably already seen this but I'm gonna paste it in there's the readme in the v2, it's very short, but it's got some FAQ so feel free to share that with others who either are not on this call, but want to get involved.

A

And/Or, obviously, you're gonna be ale to share the video with them at that point, but just wanted to to make that mentioned. We'll try to keep that updated along the way. With some of these questions that seem, like kind of oh yeah, basic good questions that that we don't already have it.

B

Cool yeah, thank you and and David I think wrote that readme and Julie and Simon have contributed there too, and so it's really good stuff.

B

If someone is keen to do project online there's a few people are talking about project I mean I'm all for it. So if folks can get together on that, but it's not on my list as a dependency for getting v2 going, but if folks want to work on it, absolutely 100% encourage that I think it'd be a great addition.

B

It's probably an entirely new library or new yeah library, I guess or new library or package I guess I should say yeah. Thank you. My brain is just slowly bringing this morning. So so, let's so we've written some tests. That's awesome! Let's look real quick at the code, so we can kind of understand a little bit of the v2 and how it operates. We have already done the structural changes to the code, so you don't have to do any v2 oriented refactoring that work.

B

It should already be done in all of these sub modules, but I think it's important for us to take a few minutes and just kind of step through what we've done and for me to explain to all of you why we've made the choices we've made, and you know, of course, always welcome feedback on this stuff but I'll to be super honest, some of its gonna, be just how it is at this point, so we've got classes still and one of the things we're really changing.

B

I want to look at this index, so these index files are exactly like the index in another module. This is what's getting exported from the regional settings, sub module and we'll see that in usage in a little bit, so the only things were exporting are interfaces and these factory functions. Okay and then you'll see this import web and we'll talk about what that is doing here in a second, but so these classes we aren't on purpose exposing them to the world anymore. It's JavaScript!

B

You can obviously always get to them right if you want to, but we're not trying to expose them, and the reason for that is because it's starting with v2, if we only give people interfaces and factory functions, we can change the guts of this to do whatever we want moving forward right. We could get rid of these class implementations and have some kind of generated partials.

B

We do all kinds of crazy stuff right and that won't break anybody so long as we supply stay true to those contracts, we've handed everybody, those contracts being the interfaces and factory functions. So the factory function in the past. You may have done something like new web blah right and given it a URL, the only difference is now you just call web and give it the URL. The signature stays the same and you can give it additional path. There, too, the signature stays the same.

B

You just drop the new keyword in your code for the factory functions, but we have these classes that actually implement the functionality right. We need some and the methods have to live somewhere or the properties have to live somewhere. So they live on these classes and we're extending the same kind of things in this case. Sharepoint there's a queryable instance and there's a queryable collection and then we're implementing this underscore I regional settings. So this is a bit and I'm gonna.

B

Ask somebody to drop on me if ba Julie, but so this is a bit of typescript juggling to make things walk in the typescript type system correctly. This isn't something you'll ever have to do in your code. You can ignore it, but it's here to build up the interfaces in the way we need them to be built up. But what this does is this creates a relationship between this interface and this, so that we know that this class implements this interface, so that gives us a bit of type-check there.

B

But this is the interface we actually are exporting, and so you can see we're extending this interface and then we're extending a couple of other things, so we're extending I and vocable and we'll look at what that is in a second and then we're extending the iqueryable SharePoint and this generic type parameter here is the default action result which in our case is result settings info. So let's uh I'm gonna move pretty fast through this there's a lot to cover. If you have questions, please, you know type them in the window.

B

I want to try and answer them. So let me drag that over there. So I can see the window as I'm talking, but so so, let's look at it. Vocable real, quick and let's we can't go to the date. Doesn't yeah. Sometimes the the linking up in vs code is really great, and sometimes it's really less great. So let's look at the invoke interface. The only thing it's doing is essentially saying this object can also be invoked as a function right and so we're creating this idea of a hybrid object.

B

That is both an object and a function which is one of the cute things you can do in JavaScript and creates and lets us have that syntax. That is SP. Look yes, boy, oh boy, web and just invoke it right, ignore whatever just happened there and we can just invoke it as a function or we have all the problem. Oh I, don't have the type check here, but you can do all the intellisense for the properties and methods and things as you need.

B

So the way this is built up is through a bunch of functional binding, which happy to talk through this with folks, if they're interested on another call, I don't spend a ton of time on it here, but at the heart of all, this is a proxy object.

B

So, if you're not familiar with this, this is a capability that allows you in JavaScript to intercept any call into an object, and so this is how we're able and I'm not going to go down this rabbit hole on this call, because this is about writing tests and getting through a checklist but I want you all to kind of have an idea of what's going on, because I hope as you get into writing this you'll be interested and look into the code and maybe maybe learn something or maybe have questions, maybe have ideas on making stuff better.

B

But this proxy is how we're able to do extension methods, how we're able to extend the different classes, how we're able to or how we're going to be able to apply different. You know, logging patterns and different method intercept patterns in the future. One example of that might be behind the scenes we might be able to, for example, rewrite requests in the ESPE library to actually hit the Microsoft graph. That's an example right and that's again, all of that being invisible to people because we're just giving them interfaces and factory functions.

B

So anyway, I don't want to dive into the available stuff really happy. If folks are interested in that, have a look at it super happy to talk through it at some point and then this is us creating our factory again. This work has been done so I, don't anticipate anyone needing to do it, but I think it's important to understand it.

B

So what we're saying is: let's create an SP and vocable Factory if you're working in the graph library there's also a graph and vocable factory function and what that does is just create up the method signatures and then we're giving it a generic parameter of this is what this factory will produce. So our regional settings for factory produces I regional settings instances, and this is the concrete class that it's going to use in that in vocable functional, binding stuff.

B

We looked at briefly just a second ago, so it's going to take that class, merge it with a function and add some other stuff and wrap it proxy boom. There's your factory, so you know neat. So, let's look back at our checklist of stuffs. Our next check those stuff, every property method has at least one test great, ensure that every all the interfaces, methods and properties are commented. So what we've done is because we have these interfaces and because we're exposing these interfaces to the public.

B

These interfaces are where the comment should live, because this is actually what will appear like in vs code or visual studio, where you're getting your intellisense. So we want to comment the interfaces, not the classes.

B

So, for example, we come down here to the time zone class, and we have this super helpful description here, describes the time zone data we're going to take that off, because no one will ever see it and we're gonna put that on the interface right, and so you can see this interface I've done a lot of this because I didn't want you all to spend time watching me. You know type comments, but so same thing. Just move that comment down.

B

If you see places where, like, for example, here we're merging the time zone instance in that way, I talked about before you know. If you see places in the code that we need some code comments for you know six months from now, when we forget what we're doing go ahead and add them in right, all of you should feel empowered to do what you think is best to make the library better right, like I said, if you're not sure on something, just ask us, but y'all are smart.

B

Y'all know what you're doing so, I anticipate you having ideas. We haven't had to make things better. So that add comments. Maybe you know change methods a little bit. This is a major release, so we can change method signatures. We can. You know it can be breaking changes, that's totally. Okay and then we've got some other interfaces here that I'm just gonna. You know, for example, here say you know this is the data for ezel settings right, that's a dumb comment, but it gets the job done.

B

So, let's come up here, and so that's good, so everything's got comments. I feel good about the comments now in this file remove comments from class implementations, so that's kind of what we talked about a second ago. There's no point in having the comments in both places: there's no point in having them just on the class. No one will ever see them so I'm gonna check that one off and I'm gonna say ensure the docs page is updated great. So we wrote our tests. We've moved the tests now out to our own test folder.

B

This is again a lot of the testing frameworks. Just assume you have a folder named test, so we're just gonna. Do that and I think it makes it a little clearer where the tests live before you might remember. They were in each package. I thought that was a good idea. I've since changed my mind. So now the tests are here: you'll just create your file for tests and write your tests, as we saw you can use some of these other ones as examples and then Docs now also is gonna have its own folder again.

B

This is something that used to be down in the package. I thought that was a good idea in the past I've since changed my mind and I. Think we just have a Doc's, folder I think this makes everybody's life mine included a little bit simpler, so you can come in here. Here's our SP folder! Some of this is outdated. This is just us getting started. So if you see stuff in here, that's outdated, you don't necessarily need to let us know.

B

We probably know if you have some time and want to update some of the stuff. That's outdated! Absolutely! Welcome that help. We can use all the help we can get on getting this stuff ready to go so I've written this documentation thing ahead of time, because I felt it might be super boring for you all to watch me. Write. Documentation doesn't make for the best TV, but so we've got a couple things going on here. I'm gonna hit this little preview thing err here, so I can kind of see.

B

What's going on we're trying to make things easy for people to understand. One of our big goals is for those of you that were at the collaboration summit and Europe heard me say this: that our focus for the last couple years has been on growth. We've achieved growth.

B

We have fantastic usage numbers now so now our focus is a better experience for folks coming new to the library or who have been using the library for a while and might not know of all the capabilities, because we've never had the time or taking the time to document them before. So we want to make our documentation super easy and really better than it has been in the past right, like I've never said our documentation was perfect and it certainly has room for improvement, and this is that opportunity to make that improvement right.

B

So we've got a couple little button things up here. You can just copy and paste these. So what we're saying is regional settings is invoke Abul and does support selective imports. These both link to articles that I need to write at some point, so they link to a blank page but- and those pages will describe what in vocable means and what selective imports means, what those concepts mean.

B

But that way we could do it once we don't have to do it on every docs page right. So we've got those tagged. I've got a table here that shows how you can do the different, selective imports and again. This is fine for here and we'll describe more about what this means on the selective imports article.

B

So don't worry about that exactly, but we're just showing here how to do these selective imports from the library right how to import things and we'll take a look at that in one second so and then there's presets again for those of you that we're in Europe the this will be a bit of a repeat but the packages because we're doing selective imports, it felt mean to make everybody change all their code immediately to use selective imports right, I'm, not a mean guy, so we didn't do that.

B

So when we came up with this idea of presets and so the all preset exports everything and basically gives you what the library, the SP library was before, with everything already attached, the SP constant, the core preset just does Ida mist sites webs and gets the the SP constant wired up for just that stuff right. These are just two examples. We can probably add more in the future. I.

B

Don't want to add a thousand presets because of some other work we're doing around the how to build your own reusable package which not going to cover on this call but presets. So that's what this is talking about. Everything is in the all preset and so for stuff like web I would have listed the core preset here as well.

B

So now we've got some code examples here, so we just jumped into this and said: here's how to get all the regional settings and here's how to select only some of those settings right, you might say to yourself Patrick. This looks a lot like the tests that we did so the way I do this and the way I think is a nice easy way to do. This is to write the tests in the docs at the same time and to use our ability to debug.

B

So if you haven't ever looked at the debug launch, folder there's a main file here and it has all this stuff and then, if we look at SP, this is where we can do some SP requests, so what I would do or what I did? In fact, for regional settings was SP web well, I don't have my regional settings right. What do I do?

B

This is where the selective imports come in so I'm gonna, say import, p and p SP source regional settings, and now I have our regional settings, property and that's all been dynamically added on to my web object. I could also do just web for regional settings. It only applies to web, so this doesn't really gain you anything, but there are other places like content types.

B

You could just grab the content type functions for web or for a list, for example, but so I've done my selective imports now I have my property, so I would do this and now I can hit f5, and this will run, but first I want to go to my little debug window and make sure you picked debug, not debug tests, not debug build system, but just debug and we'll look at debug tests in a second time is flying so so hit a 5.

B

This is going to run we'll get our regional settings back and you can see this is super complex, I'm, just getting it and I'm dumping it to the console. So we can see it worked and it worked. No. It.

A

Worked, it worked, it.

B

Worked so we can see this is some logging happening it worked. So this is how I also created those interfaces. I just copied this and made it in an interface. You can do the same thing if you find places where that could help, and so what I did is just go back and forth. Write these examples test them here. Put them in the docs write a test for it same thing for installed languages, time zones, and you can see we're trying to show a bit more of the library. So we can say, hey, look.

B

You can select stuff out of here right, you can. This is getting by ID. This is calling something from the get by ID. We just did right. We've got a list of IDs here, so we're trying to be as helpful as we can. But again this isn't a place. I expect anybody to write four hundred thousand lines of samples and examples right. It's not the best use of your time and honestly folks aren't going to read them. Folks want the basic stuff to get started and that's good.

B

This is another place as we get issues come in people have questions we'll come in here and update the docs with a sample to fix some issue or to show how to do some capability that isn't already in the docs right.

B

Maybe it's some special case about how to do something with time zones which I can't think of anything special time zones but and that's it so I just went through, did my tests hit at five random do to do to do, and one thing you want to do is don't check in because I made this mistake, don't check in any changes to this SP file, so you can just discard those another way to work. Is you could come in here and I could add a new file and call this original settings?

B

Ts I could do all my coding in here, like I, would start with just look whoa. That's not the right file. I would just start with this. Whoops start with this and then I would update this I could change main to be my regional settings, and then my regional settings file will run writes exact same way. The other file did the git ignore is set up, so you can have any number of files in here and they will get ignored. The only things that get included are SP main graph and this TS config.

B

So you could have thirty different little testing files in here. If you wanted and then, but the same rules applied, don't check in any changes to main because that'll mess up the next person down the line might ripped up Julie by screwing up that exact thing, so just try and keep an eye out for that. That's something we'll check! We merge the pull requests, so we've removed comments, we've ensured the docs are updated, so the next there's two things left I think we'll just have time to do them.

B

So one of the last things is to come to the issues list and we're gonna go back the issues list and there's one of the things we did is search for things with the label sample and you're gonna get some stuff here right. None of this I I just know. None of this has to do with regional settings. But for some of this this is places where people have asked questions like here's. Let's just I, don't remember what this is. Let's have a look at it.

B

Here's somebody saying you know: here's how how do I to work with items in a batch right, so we don't didn't, have a great example of doing that. So for whoever ends up writing the batching article. This is a thing you might come and look at this. Then you might go. Look at this issue kind of understand the questions and look Andrew. Who always does these amazing examples?

B

We can just steal his sample right right, a little documentation, a header above it and be like this is an example. What's this person yeah? So this is a guy. A guy asking how to set up a batch depends on another batch right, so here's a sample to do that. So in your Docs, you just make a header. This is how to depend on a batch put this sample up there linked to this issue. If you'd like- and you know, you're all set, so that's kind of what we mean by this one.

B

So we're just trying to pull back out those places where we definitely had a gap in the docs and make sure we've closed that gap as we moved to v2 and then finally- and this is kind of the most complicated step that is probably also the biggest pain in the bum, but you need to go through and I happen to do with regional settings.

B

There's been no changes for the last three years, but you want to look at the 1x branch and ensure any fixes updates and changes have been moved to the oh, so you kind of have to go line by line through the code. Most of it hasn't changed, but what's happened is this dotto branch like I said no longer is related to the the dev 1x branch and I also branched it four or five months ago, six months ago, at this point, maybe maybe not that long, but a long time long enough that stuff has changed.

B

Stuff has been improved. You know, we've had what three or four releases in that time. So you got to go through the code and really just kind of line by line review, but most of it hasn't changed, but in some places you have right. For one example was like the client-side pages: I had branched the v2 branch before we rewrote all the client-side pages stuff, so I had to bring all that work over write.

B

It just had to get done right. It just takes some time. You just have to do it, so hey cool I have done all my checklist. I feel really good about it. So now, I'm gonna go back to my code and the last thing you want to do before you check all this in and submit a pull request. It's always a good idea see what files you've changed. I've changed a few other files as I was going through this yesterday with Julie and Simon, and David I noticed a few things. I wanted to correct.

B

So you could ignore some of this. But, for example, like I've, hey, here's, our docs page for the settings file. It's a to do right, but it's gonna remind us. So here's my Doc's one last look at that looks good okay.

B

This was me fixing a linting thing so ignore that you wouldn't have done that. Ignore that so here's our types go through my comments, look good! My classes, look good! You can see where I've moved comments around and things you can see down here. I've added some interfaces.

B

But that's you know, so that's looking at this here's web I made sure this was commented. Oh I didn't mention this. So sorry, real quick in this, you have your index, which is your exports. You have your types, which is the classes and interfaces, and then you have one or more of these other files named like web or lists, and these are the things that actually do the dynamic attaching of properties and methods to the interfaces. So, like I said this work has been done.

B

You will shouldn't have to refactor any of this, but have a look at it, and this is again some type script juggling where you can actually augment this module. So we're saying declare this module here and typescript is smart enough to actually merge these things together and then we're gonna, say the interface and the interface here we have to add our property to both of them just to make typescript happy, but this augments, the actual interface people, will see.

B

You saw how that work when we were trying to debug and then this is us calling our little helper function to add a property. So if we go to that, I can't go to that. Sometimes that's so. Here's our add property, which is really just doing a reflect defined property on our prototype and adding that property and you'll see in places. Let me just show you this, because some of you will see this. If we look at sharing I'll, have it right, so we look at web.

B

We're actually, then, just also attaching methods right to the prototype of that underlying object. I spent a lot of time trying to figure out the best way to do these dynamic methods and played with like putting stuff and arrays doing all this kind of stuff, and then what I really settled on is JavaScript already has an object.

B

Graph, that's supported and that's the prototype so we're just gonna use it, and so we're just attaching stuff to our prototype here and so for the sharing we've actually centralized everything and made things a little easier, but ignore sharing I think Julie took sharing. So none of you have to worry about that.

B

So, looking through my files, I'm happy with my changes. I did a couple little things, so the client-side pages tests so ignore that and in my regional settings tests those look good I feel good about what I've done so now. I need to check it in now, I need to submit a pull request, so this is sort of the last step that doing one of these modules. So if you've never done a pull request before never done any of this, let's walk through it.

B

So the first thing I need to do is I need to do a git. Add, and you can add specific files. You can add directories get add. Dot is just gonna. Add everything here before I. Do that I always like to do this get status?

B

That's a great command, so you can see exactly what you're gonna add and commit, and this to me is my final sort of mental checkpoint to say: okay, great I haven't changed, something I shouldn't have I haven't changed like that: SPE launch file, for example, so I'm gonna do a git, and now you have to do a git commit and that commit is going to be regional settings sub module.

B

That's as complicated as it needs to be, if you like, you can put a 2.0 in front of this to help us understand so we're gonna commit now I'm gonna push, so this push is pushing into my fork in github, so the code. Now, if we go to github and we go to Patrick Rodgers and we go to nope, why did it do that?

B

Go to my for gov PPG's? There we go! So if you look at my fork, we can actually see now. If we get into the correct branch we can see in sp under docks, for example,.

B

No I'm, sorry I am just all over the place. Stocks SP. So you can see our regional settings page is here in my fork. So we need to get this from my fork into the main repo. So you can see here's my thing fork from this thing. So the way we do that is create a pull request. So I'm gonna, say new pull request and you're gonna get this screen, which is going to tell you all your changes. You can review things again, but the important thing here is you're.

B

Going from whatever you call, you can call your dovey to other stuff. You can create feature branches, I, don't care! You do work, how you want to work but target the dev v2 branch here, if you change it, for example, to doe it's just gonna tell you it can't merge right, it's they're not related, so it's a little bit of a safety there, but so we'll just go to dev v2. This is telling me I'm able to merge if it says you're not able to merge.

B

That is okay, it's not at the end of the world, but what you want to do is see if you can fix some of that stuff or it might be because of you started working. Somebody else submitted a pull request, so you need to do. I talked about the beginning is pulled down. The upstream changes, merge them and resubmit your pull request. So this would be there'd, be a button here to create your pull request.

B

What's a little funky is I already had an open pull request, so the way github works is it's become part of this pull request, which is fine in this case, because all I'm reviewing these, but each pull request. Would please be one sorry one sub module, so you can see here's SP view sub module, not a deep did. This haven't had a chance to review it. Yet so what will happen? Then? You just go back to your issue.

B

That was wherever my she was and I would say in here. I would say: hey folks, PR submitted and ready for review great, and so somebody David Simon Julie me will come through and say: hey thanks. That's great really appreciate it. I'll give myself a thumbs up good job, Patrick and change this to. Actually this will remain in progress for now we'll review your pull requests when we have time so don't this is I mean these have been sitting here for a while we're gonna get them reviewed. Don't stress about that?

B

It's more of a free time issue to get these reviewed so because there's a lot to review right all the stuff we've just gone over so we'll get these reviewed, we'll get these merged. If, if you like, want to do another thing and submit another pull request or something you can, let us know, and we can sort of jump in our priority. Reviewing your sub module, I'm gonna, try and get to these next week. I hope have some time to do that and then your issue will move through. We have a project here.

B

I think this is all public I'm, pretty sure this is all public, so you can see where your issues are in the tree of stuff. So we have a volunteer to you offer to review the docs so you're. You know regional settings will then move over here, ready to review Docs and then we'll move it to final review and then move it to ensure attribution. So we can make sure everybody gets credit for the work they've done, because we want to not miss anybody and then finally I'll end up on done and that'll.

B

Be that so with that I will stop. I have one minute for questions, so any questions from anybody I'll bring this back over. Here. um Let's see any questions. Yes, we are gonna get this onto YouTube.

B

Probably early next week, I'm thinking so we'll see any other questions, as we finish up here, cool well with that I'll just say. Thank you to all of you for joining this call. I, really appreciate it appreciate your interest in helping us I'm really excited to get you all involved, and then, if you have questions like I said reach out to pick one of the issues comment on there with your questions, your ideas, whatever would love to hear them and then I would be excited to get as many of you involved either.

B

The folks that made the call or those of you watching this at a later date would love to get you involved and love to get you helping out.

B

So please, if you interested just reach out or just pick an issue and look forward to working with you so thanks, everybody I, really appreciate, really appreciate everybody, your offer to help and your interest in helping it's really exciting, to see that so v2 will be our best release ever and it's gonna be a big credit to all of you out there in the community helping to make that happen. So everybody have a great rest of your day, rest of your Friday or a rest of your whatever day.

B

It is when you're watching this and we'll all talk soon. Thanks all I.