Repository files navigation

Thedocumentation site for the open source Content Management System DNN (formerly DotNetNuke).

The project uses thedocfx library to pull XML comments from the DNN Platform source code and combine that with articles written in Markdown to form the documentation for DNN.

If you do not have Git installed, you will need to install it first. You can find instructions atGit's Installation Guide.

The next step is to fork this repository from GitHub to your own GitHub repository in order to give you write access on your own copy (if you don't have a GitHub account, you can create a free one).Simply click the Fork button above to get started.

After your own fork is created, you need to copy the repository into your local machine, this is called cloning. This will create a copy of the DNNDocs Git repository (its directories and folders) on your local machine so that you can work with them there.

The following command will clone your forked repository to your working directory, so you may wish tocd to an appropriate directory first.

git clone https://github.com/your-github-user-name/DNNDocs.git

The previous command will have created a folder titledDNNDocs in your working directory. So, for example, if you had been working inC:\dev\, the previous command would have createdC:\dev\DNNDocs\.

cd DNNDocs

The references from your local copy (clone) to their respective GitHub repositories are calledremotes. By default the previous clone automatically setup a remote calledorigin to your fork on GitHub and you have read-write access to it (you canpull andpush to it). In order to be able topull the latest changes from other contributors on the official DNNDocs repository, you need to setup another remote to it, we call that remoteupstream. In order to set it up, run the following command:

git remote add upstream https://github.com/DNNCommunity/DNNDocs

Unless you are part of the DNNDocs core team, you will only have read access (you can onlypull) to this remote.

You should ensure that you already have.NET 5.0 (used by thebuild project) and the "Developer Pack" for.NET Framework 4.6.2 (used by the customDocFx plugins) installed on your machine before trying the build process.

You should now be able to run the development version of the docs locally with the following command:

Windows Powershell:

.\build.ps1

Windows CommandLine:

build.cmd

Mac/Linux:

.\build.sh

The compilation process could take quite a while. You may see some warning messages. Eventually, you should see a message similar to:

Serving "C:\dev\DNNDocs\_site" on http://localhost:8080

You can now openhttp://localhost:8080 in your web browser to view your local DNNDocs app.

You are now all setup to start your first contribution.

First, it is recommended to create a new branch to collect your changes without touching themain branch, this will make it easier later when you will need topull the latest changes from theupstream remote (the official repository). You can use any branch name that makes sense to you as long as it does not have spaces or special characters other than - and _. Popular naming conventions are something that describes the issue solved or simply the issue number. To create a new branch you can type the following command:

git checkout -b your-branch-name

Next you can start editing documentation and saving files using your favorite text editor (Visual Studio Code, Atom, Sublime Text, Brackets Notedpad++, etc). When you are done with your changes you can verify the modified files. Some code editors will actually show a status of the modified files in their UI. If you want to verify it using the command line you can run the following command:

git status

In Git parlance, a logical set of changes is called acommit. All your current changes are just temporary until you actuallycommit to propose them, hence the namecommit. To create a commit you first need tostage your changes, this is adding the files you want to commit into a list (staged changes). For simplicity, we are assuming that all the changes you saw ingit status are to be included in the commit. To stage all changes, run the following command:

git add .

The. above means all changed files, if that is not the case you can replace the preceding command with either a globbing pattern or each filename you want to stage for the commit. If you want to verify what is staged or not staged, you can repeat thegit status command.

Now that we have selected what goes into thecommit, let's actually create our commit using the following command.

git commit -m "Here you can enter a commit message that summarizes the changes in this commit."

Congratulations, you have created your first commit! The next step is to push your local branch to the web, because right now this commit only exists in your computer. This step is called apush. Without parameters, thepush command pushescommits to the defaultremote (in our caseorigin) into the same branch. The problem is that our branch is currently only local, so we need on the first push to specify theremote and thebranch name. Again, most code editors have a UI to make this simpler, but in the command line, the command would be:

git push -u origin your-branch-name

Now your changes are available in yourfork of the repository for anyone to view. Remember how you only have read access to theupstream (or offical repository)? Since we cannot push there, they need to pull. The next and last step is to propose your changes, or in other works, request from DNNDocs team topull your changes, hence the namepull request. You can create apull request directly in the browser, if you navigate the the origin or the upstream repositories any soon, you will see a banner showing the recent pushes and a button to create a pull request. If for some reason you do not see that banner, navigate to your fork and select your branch in the branches dropdown, you will see a "Create Pull Request" button.

Congratulations, you just created your first pull request!

A couple of days or weeks have passed and you are still all setup to continue contributing, but sice time has past, other awesome contributors have been working hard and nowupstream,origin and your localclone may be out of sync with different content. Let's bring those back in sync. Remember how you can only read (pull) from the official repository (upstream remote) but you can read and write (pull andpush) to your fork (origin remote). This means we will need to pull from upstream to your local clone and then push this back to your origin to get the 3 back in sync. But first we need to change our branch to the default (main) branch. Here is the series of commands to do what is explained in the paragraph:

git checkout maingit pull upstream maingit push

Everything is now updated per the latest changes everywhere, you are ready for your next contribution, scroll up and repeat from the "create a branch for your changes" step, rinse and repeat.