Projects
Quick-start guide for starting a project
This page helps you do the basics you need to start a project on IEEE SA OPEN. There are many reasons for creating a project:
- You have an open source project, or a software project you want to convert to open source, and are attracted by the tools and processes provided by IEEE SA OPEN.
- You are working on an IEEE standard, or a project you hope to get accepted as an IEEE standard, and want it to be open source.
- You are a programmer or student with an idea for a new software project, and want to benefit from the guidance IEEE SA OPEN provides on modern software engineering and open source methods.
This quick-start guide complements the official maintainers manual provided by IEEE SA OPEN.
Types of Projects
It's useful to discuss different needs for three different levels of projects.
- Personal project: this is the smallest, simplest type, run by one person with help from others. Imposing a lot of infrastructure would just be a waste of time. If successful, this kind of project can proceed to the next stage, the large project.
- Large project: this has a couple dozen or more contributors. It needs more governance and infrastructure than a personal project. If the leaders want to propose an IEEE standard or get other kinds of help from IEEE, they can proceed to the next stage.
- Official project: this project demonstrates that it meets strict reqirements for governance, legal compliance, code quality, and documentation defined by IEEE SA OPEN. Project leaders present the project for approval to the board that runs IEEE SA OPEN, the Open Source Committee (OSCom). Official projects receive a great deal of attention, guidance, and advice from IEEE. They get legal advice to avoid problems with anti-trust laws and other regulations. If the project wants to establish an IEEE standard, the IEEE guides them along that process.
Some of the guidance in this document apply to all three kinds of project, and some guidance applies to higher levels. As you move up to higher levels, please consult the maintainers manual. In general, the recommendations in the maintainers; manual are valuable for all projects. They are certainly required for official projects. On the other hand, some rules may be overly complex and unnecessary for personal projects.
Prerequisites
Every project should do the following before joining IEEE SA OPEN.
- Form a team
- Make sure existing code or contributions are owned or licensed properly
- Write essential documents
Form a team
A personal project might start with just one person; larger projects probably already have multiple contributors and hopefully have rules and processes for managing contributions. But as open source projects, they all should invite a diverse range of contributors and define clear management rules. Consider such issues as:
- How are decisions about new features made?
- Who gets to approve a code change, and what criteria do they use?
- How often are meetings held, and who attends?
- How are group members promoted to higher levels of responsibility?
- What is the succession plan for providing new leadership?
Choose a project leader, and set up a technical steering committee to handle technical decisions such as what tools and languages to use, what coding standards to enforce, etc.
More information can be found in sectioon 2.1, "Governance principles" in the IEEE SA OPEN maintainers manual.
Make sure existing code or contributions are owned or licensed properly
Every contribution to your project--particularly code, but also other materials such as documentation--should be under an open source licence recognized by IEEE SA OPEN. This requires a Contributor License Agreement (CLA). If you haven't been asking people to ensure that their contributions are open, you must to each person or company who contributed and ask them to sign your agreement.
Too many projects are lax about demanding CLAs. When they want to go public or become open source, they found that they're using code they don't own. They may discover that the owner of the code didn't intend it to be used under the license chosen by the project, and may have plans to commercialize it. In any case, lacking a CLA, the project has to strip out the code. If it has been in the project for a while and others have built on top it, it could derail the project.
There are two ways to get contributors to conform. The best way is for them to give ownership to the project. This does not limit anyone's rights in an open source project, because everyone is free to use the code under the open source license. The alternative is to let the contributor keep ownership, but to put the code under an open license. This is sub-optimal for many reasons, so keep things simple and require a CLA. Sample CLAs approved by IEEE SA OPEN are on their web site.
Write essential documents
This section lists documents that are useful for open source projects. Some should be written before creating an IEE SA OPEN project, while others can wait till later. Similarly, your initial documents can be short and you can add detail to them later. At the start, you may need only the README.md and the Contributor License Agreement.
README.md
This is a general place for new people to go. You should highlight the file on your site after you set up your project. You can put plain text there, but it also accepts a very simple kind of formatting called Markdown that allows more attractive headings and lists. A short guide introduceing Markdown is available. A table of contents is useful for this document as it gets longer.
Think of the basic things a new member of your group will ask when joining a project, and put them in this file. Examples include:
- Project description.
- Team lead, committers, and other key leaders, with their contact information, time zones, and available times. We discourage the inclusion of email addresses for reasons of privacy. Instead include their chat handles, once they are all set up on opensource.ieee.org.
- Pointers to important documents that enforce good community behavior, such as the IEEE Code of Conduct.
- Keywords for search purposes.
- How to sign up for the announcement list.
- Location of discussion forum, chat, and bug or issue tracker, once you are set up on opensource.ieee.org.
- Conventions for submitting a bug report.
- Any earlier names and code names for the project.
Contributor License Agreement
This was described in the "Prerequisites" section. Do not let people become members until they sign the agreement.
CONTRIBUTING.md
This contains guidelines for contributors. It can grow quite large, because a well-run project has to enforce rules on how to make features requests, how to code, how to run tests, and more. A table of contents is useful for this document.
Start by pointing to the README.md file for community guidelines and information about leaders and committers. When time permits, add:
- Code conventions
- Testing conventions
- Branching conventions
- Conventions for commit messages
- Steps for creating good pull requests
- How to submit feature requests
- How to submit security issue reports
- How to write documentation
- Project dependencies
- Build schedule
- Sprint schedule
- Road map
- Helpful links, information, and documentation
- When the repositories will be closed to contributions
HELPWANTED.md
This file isn't found on every project, but it can be very useful in recruiting people to important tasks. New members can't be expected to scrutinize your bug database or think up a feature to work on. In this file, you can list your project's greatest needs. These aren't limited to coding--they can include advocacy, marketing, documentation, fund-raising, or anything else to benefit the project.
You can also set a forum where requests and offers of help are posted, and link to that forum in this file.
GETTINGSTARTED.md
This material helps a potential contributor set up tools and begin coding. The material can be in a separate file is it's complex, or be folded into the README.md or CONTRIBUTING.md file. Writing this material is a good project to ask an intern or other new user to do. Feedback from contributors can improve and flesh out the information.
Set up a technical steering committee
The technical steering committee (TSC) brings together technically sophisticated members of the project and embodies the vision for the project. The TSC makes the most important technical decisions regarding the project: which markets or users it is meant for, what features and interfaces to develop, what architecture to use, what language and tools to employ, and more.
All technical decisions require an understanding of current practices as well as a deep sensitivity to particular needs of the project. Technical leaders should keep researching current innovations in tools, languages, and architecture while avoiding the temptation to jump into something because it's a fad. The question is: does the new technology meet the current and future needs of the project?
Activities of a TSC include:
- Defining goals
- Defining use cases and markets
- Project architecture
- Choosing the toolchain
Choose a project name and location
Official projects start with the prefix "ieee-". Other guidelines for choosing a name are:
- Avoid trademarks
- Don't use flippant or overly difficult names
Project Tools
The following tools are the basis of modern software engineering, and are needed by almost every project.
Chat Channels
The IEEE SA OPEN platform has integrated the open source Mattermost chat application with our GitLab. Mattermost is similar to the Slack service popular in many businesses. To set up a chat channel, follow the instructions in Mattermost Basics.
Chat channels are often a primary form of communication for project members, especially given the varied locations of our volunteers and the time zone differences those cause. Although at first glance a chat application shows a few simple purposes, such as discussing features and offering help, chat channels actually serve several critical functions:
- Education. New project members are initiated and guided here, and anyone can ask for and offer help.
- Deliberation. All sorts of community decisions are discussed (sometimes too much) on forums, such as new features, user interface elements, and project direction.
- Documentation. The answers provided to user questions are preserved so that others can find them later. The arguments and possibilites floated that make up a decision are also preserved for historical purposes. A good search feature is important to enable these benefits.
- Community building. People get to know and trust each other through discussion.
- Inclusion. Every project member can watch and participate in decisions.
Because forums fulfill so many functions, a project often creates several different forums for different functions: newbie questions, technical design decisions, project governance, etc.
Community inclusion and trust require all important discussions to be carried out or shared in the channels, where all members can see them. Some sensitive issues such as policies regarding paid staff or legal issues may require private discussions.
Bug tracker
GitLab has built-in bug tracking, like many other common project tools.
It's crucial to make sure that bug reports are answered. First of all, bugs make the product less useful, and may introduce dangers. Second, you want to show users that your project is responsive. Fixing bugs is one of the most direct ways to do this.
Of course, many bug reports can be traced to user errors or a misunderstanding of the product. It is good community relations to respond as fast as possible, offering polite and helpful information.
Most projects designate people to evaluate incoming reports, with the goal of providing an initial response to every report within days. Bug tracking systems such as Jira let you classify the severity of each error and track the progress in solving it. Bug reports that represent real bugs may be assigned to an individual, or simply publicized in the bug tracking system. All community members who are able to fix bugs are encouraged to choose bugs and fix them. In fact, bug-fixing is the classic starting point for aspiring new developers.
Version control
Any text that people work on and change should be stored in a system that makes changes easy to track. This is called *source control*, and ensures that developers can:
- See what was done over time, who made each change, and the differences between files at different stages (versions)
- Assign version numbers and tags or labels (such as "stable" or "released")
- Revert to earlier versions if necessary
- Create separate versions (branches) for separate groups of developers to work on in parallel, and merge their work when it's ready to be integrated
GitLab is based on the open source Git tool, probably the most popular source control system, and certainly the most popular open source one. Gitlab stores the source code, making it easy to share and removing worries such as downtime and backups from the developers. However, many developers using GitLab install Git on their personal computer systems too, so they can keep their changes there before pushing them into GitLab.
Testing and continuous integration/continuous development (CI/CD)
CI/CD is central to modern development environments because it automates testing and deployment. GitLab offers built-in CI/CD through a menu item.
Software usually requires a build process before it can be tested or distributed. Various tools, such as Ant and Gradle, offer a structured way to define and run the builds. Some types of document development also requires a build--for instance, to create a web page or PDF from the file in which the writer is working. CI/CD is your way to automate the build.
Testing is critical to prevent regressions (bugs that break the way software works). To catch bugs early, developers should use CI/CD to run their tests at each stopping point in their coding. CI/CD allows the tests to be run on each commit, so that a bug can't even be checked in. (Of course, developers can't anticipate every bug, so some will slip through the testing process.)
Finally, CI/CD can deploy a software package or document to the location where it can be used, and notify people that a new package or document is available.
Wiki
This may be useful on large projects to make it easy for members to write and update documentation. A wiki can also record decisions and show how they change over time.
Set up project activities
Regular processes should be in place for:
- Code reviews.
- Bug fixing. Recruit good coders to keep on top of reports, determine whether a report is accurate, and direct accurate reports to the people who can fix the problem. These volunteers should also politely respond to each report.
- Sprints and codeathons, if your team uses them.
- Education for new members.
- Meetings. For legal purposes, IEEE SA OPEN requires that each project hold regular team meetings, record the names and affiliations of all participants, and keep public minutes.
Some other major activities follow.
Budgeting and finance
A trustworthy member should be chosen as treasurer. The project should follow all the proper financial practices of any organization, such as preserving receipts for expenditures and sharing budgets regularly (such as once a month) at project meetings.
Measuring progress (metrics)
Measurements play several valuable roles, including:
- Revealing who has contributed, and thus contributing to members' morale and their desire to contribute
- Gauging the effectiveness of the project (e.g., new product features, the rate of addressing bug reports)
- Gauging the health of the project and identifying aspects that need work
Luckily, modern tools make it easy to collect many measurements through automated tools. You can set up and get access to metrics in GitLab through an icon on the left side of the screen.
Rewards
Volunteers come to a project for many reasons. Experts want to create standards around their practices, students come to hone their skills, and everyone wants to make better technology for the world. But at all levels, people appreciate being rewarded for their work and will contribute more if they feel rewarded.
Many projects offer points or badges to key contributors. Important contributors can also be promoted into new roles, such as committers or board members.
Besides technical contributions, the project should track help with documentation, marketing, advocacy, work with outside organizations such as IEEE SA, and anything else that is important to the success of the project.
Metrics are crucial to rewarding contributors. And these must be meaningful metrics that reflect real achievements; otherwise they can offer perverse incentives to do things like make worthless commits. See the section "Who has contributed".
Reports based on the metrics should also be shared with the community regularly, so that community members see how much activity is going on. Some of the things you can report are the number and size of each pull request, along with the name of the person submitting the pull request, and project resources used during that time period.