My Readme Essay

It's Important.

Just as Code Style, API Design, and Automation are essential for a healthy development cycle, Repository structure is a crucial part of your project's architecture.

When a potential user or contributor lands on your repository's page, they see a few things:

  • Project Name
  • Project Description
  • Bunch O' Files

Only when they scroll below the fold will the user see your project's README.

If your repo is a massive dump of files or a nested mess of directories, they might look elsewhere before even reading your beautiful documentation.

Dress for the job you want, not the job you have.

Of course, first impressions aren't everything. You and your colleagues will spend countless hours working with this repository, eventually becoming intimately familiar with every nook and cranny. The layout of it is important.

Sample Repository

tl;dr: This is what I recommend.

This repository is available on GitHub.

Let's get into some specifics.

The Actual Module

Your module package is the core focus of the repository. It should not be tucked away:

If your module consists of only a single file, you can place it directly in the root of your repository:

Your library does not belong in an ambiguous src or python subdirectory.

License

This is arguably the most important part of your repository, aside from the source code itself. The full license text and copyright claims should exist in this file.

No excuses.

Setup.py

If your module package is at the root of your repository, this should obviously be at the root as well.

Requirements File

A Pip requirements file should be placed at the root of the repository. It should specify the dependencies required to contribute to the project: testing, building, and generating documentation.

If your project has no development dependencies, or you prefer development environment setup via , this file may be unnecessary.

Documentation

There is little reason for this to exist elsewhere.

Test Suite

Starting out, a small test suite will often exist in a single file:

Once a test suite grows, you can move your tests to a directory, like so:

Obviously, these test modules must import your packaged module to test it. You can do this a few ways:

  • Expect the package to be installed in site-packages.
  • Use a simple (but explicit) path modification to resolve the package properly.

I highly recommend the latter. Requiring a developer to run setup.py develop to test an actively changing codebase also requires them to have an isolated environment setup for each instance of the codebase.

To give the individual tests import context, create a tests/context.py file:

Then, within the individual test modules, import the module like so:

This will always work as expected, regardless of installation method.

Some people will assert that you should distribute your tests within your module itself -- I disagree. It often increases complexity for your users; many test suites often require additional dependencies and runtime contexts.

Makefile

If you look at most of my projects or any Pocoo project, you'll notice a Makefile laying around. Why? These projects aren't written in C... In short, make is a incredibly useful tool for defining generic and platform agnostic tasks for your project.

Sample Makefile:

Other generic management scripts (e.g. manage.py or fabfile.py) belong at the root of the repository as well.

Regarding Django Applications

I've noticed a new trend in Django applications since the release of Django 1.4. Many developers are structuring their repositories poorly due to the new bundled application templates.

How? Well, they go to their bare and fresh repository and run the following, as they always have:

The resulting repository structure looks like this:

Don't do this.

Repetitive paths are confusing for both your tools and your developers. Unnecessary nesting doesn't help anybody (unless they're nostalgic for monolithic SVN repos).

Let's do it properly:

Note the "".

The resulting structure:

Readme file is a small document, which is usually attached to the program. Readme files are written by software developers and contain basic information about the program, including the info about the installation or management of the system settings, contact information, license, gratitude, and information about the software version. To distribute the software it is important to know how to write the Readme file. Poorly written Readme document can be frustrating, tiring for the user, while a good one will help him to easily learn the basic information about your program.

Let’s create a good Readme file.

1. Include the contact information. This is probably the most important part of the Readme document. Contact information will allow the user to contact you to ask something, correct the error, or pay for the program. Include your website, Email and phone number (this information will take a couple of lines):

2. Include the date in your Readme. It is a small but very important step. It is important to indicate the date of dissemination of your program. So users will be informed of the update version of the program and will be able to determine whether it is supported so far.

3. Write down the program title and version at the top of the document. Below, write the price for the full version. If you distribute the program using physical media such as CD, you may not include the information about the price, because users have already paid for the program.

4. Give a brief description of your program in one or two sentences. For example: “This application tracks the user’s temperament by analyzing how he moves the mouse, and then changes the desktop space to adjust his emotional state”.

If your software has a long list of features, you can expand the description in a paragraph or two.

5. Describe the minimal requirements for the program. Readme file should have the information concerning the minimum requirements for the program and installation instructions. If the installer needs another piece of software, do not forget to mention it.

6. Include the information about the license and copyright. At the end do not forget to enter the information about the date of the establishment of copyright and licensing program.

Still don’t fully understand how to create a Readme file? Don’t worry – our experts know how to help you. No matter how soon you need your assignment to be done and what its difficulty level is, you can count on Assignment.EssayShark experts. Our specialists work within various technical disciplines and can help you within the shortest possible time. 

You can also be interested in HTML/CSS sample on text Hello posted before.

SamplesEditor

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *